comments updated, also for the use with PasDoc.

git-svn-id: svn://svn.code.sf.net/p/ultrastardx/svn/trunk@1269 b956fd51-792f-4845-bead-9b4dfca2ff2c

1 files changed, 152 insertions, 41 deletions

diff --git a/Game/Code/Classes/UPlatformMacOSX.pas b/Game/Code/Classes/UPlatformMacOSX.pas
index 223908d4..1da83c9c 100644
--- a/Game/Code/Classes/UPlatformMacOSX.pas
+++ b/Game/Code/Classes/UPlatformMacOSX.pas
@@ -1,74 +1,149 @@
 unit UPlatformMacOSX;
 
+interface
+
+{$IFDEF FPC}
+  {$MODE Delphi}
+{$ENDIF}
+
+{$I switches.inc}
+
+uses
+{ Used from Classes:
+  Classes
+    TStringList
+    TFileStream
+}
+  Classes,
+
+{ Used from UPlatform:
+  Types
+    TDirectoryEntryArray
+  Overriding parts of UPlatform:
+  Functions and Procedures
+    Init
+    DirectoryFindFiles
+    GetLogPath
+    GetGameSharedPath
+    GetGameUserPath
+}
+  UPlatform;
+
+type
 {
- Note on directories (by eddie):
- We use subfolders of the application directory on tha mac, because:
- 1. Installation on the mac works as follows: Extract and copy an application
+@abstract(Provides Mac OS X specific details.)
+@lastmod(August 1, 2008)
+The UPlatformMacOSX unit takes care of setting paths to resource folders.
+
+(Note for non-Maccies: "folder" is the Mac name for directory.)
+
+ Note on the resource folders:
+ 1. Installation of an application on the mac works as follows: Extract and copy an application
     and if you don't like or need the application anymore you move the folder
     to the trash - and you're done.
- 2. If we would use subfolders of the home directory we would have to spread our
-    files to many directories - these directories are defined by Apple, but the 
-    average user doesn't know them, beacuse he or she doesn't need to know them.
-    But for UltraStar the user must at least know the songs directory...
- 
-    Creating a subfolder directly under the home directory is not acceptable.
+ 2. The use folders in the user's home directory is against Apple's guidelines
+    and strange to an average user.
+ 3. Even worse is using /usr/local/... since all lowercase folders in / are 
+    not visible to an average user in the Finder, at least not without some "tricks".
 
- More on this from KMS aka mischi
+ The best way would be to store everything within the application bundle. However, this
+ requires USDX to offer the handling of the resources. Until this is implemented, the
+ second best solution is as follows: 
 
- Handling of resources and folders should follow these lines.
+ According to Aple guidelines handling of resources and folders should follow these lines:
 
  Acceptable places for files are folders named UltraStarDeluxe either in
  /Library/Application Support/
  or 
  ~/Library/Application Support/
  
- Then 
+ So
  GetGameSharedPath could return 
- /Library/Application Support/UltraStarDeluxe/Resources/
+ /Library/Application Support/UltraStarDeluxe/Resources/.
  GetGameUserPath could return 
- ~/Library/Application Support/UltraStarDeluxe/Resources/
+ ~/Library/Application Support/UltraStarDeluxe/Resources/.
+
+ Right now, only $HOME/Library/Application Support/UltraStarDeluxe/Resources
+ is used. So every user needs the complete set of files and folders.
+ Future versions may also use shared resources in 
+ /Library/Application Support/UltraStarDeluxe/Resources. However, this is not
+ treated yet in the code outside this unit.
 
- USDX checks, whether GetGameUserPath exists. If not, USDX creates its.
- The existance of needed files is then checked and if a file is missing
+ USDX checks, whether GetGameUserPath exists. If not, USDX creates it.
+ The existence of needed files is then checked and if a file is missing
  it is copied to there from within the Resources folder in the Application 
  bundle, which contains the default files. USDX should not delete files or 
  folders in Application Support/UltraStarDeluxe automatically or without 
  user confirmation.
 }
-
-interface
-
-{$IFDEF FPC}
-  {$MODE Delphi}
-{$ENDIF}
-
-{$I switches.inc}
-
-uses
-  Classes,
-  UPlatform;
-
-type
   TPlatformMacOSX = class(TPlatform)
     private
+{ GetBundlePath returns the path to the application bundle UltraStarDeluxe.app.
+}
       function GetBundlePath: WideString;
+{ GetApplicationSupportPath returns the path to 
+  $HOME/Library/Application Support/UltraStarDeluxe/Resources.
+}
       function GetApplicationSupportPath: WideString;
+{ see the description of @link(Init). }
       procedure CreateUserFolders();
     public
+{ Init simply calls @link(CreateUserFolders), which in turn scans the folder
+  UltraStarDeluxe.app/Contents/Resources for all files and folders.
+  $HOME/Library/Application Support/UltraStarDeluxe/Resources is then checked
+  for their presence and missing ones are copied.
+}
       procedure Init; override;
-
+{ DirectoryFindFiles returns all entries of a folder with names and booleans 
+  about their type, i.e. file or directory.
+}
       function  DirectoryFindFiles(Dir, Filter: WideString; ReturnAllSubDirs: boolean): TDirectoryEntryArray; override;
-
+{ GetLogPath returns the path for log messages. Currently it is set to
+  $HOME/Library/Application Support/UltraStarDeluxe/Resources/Log.
+}
       function  GetLogPath        : WideString; override;
+{ GetGameSharedPath returns the path for shared resources. Currently it is set to
+  /Library/Application Support/UltraStarDeluxe/Resources. 
+  However it is not used.
+}
       function  GetGameSharedPath : WideString; override;
+{ GetGameUserPath returns the path for user resources. Currently it is set to
+  $HOME/Library/Application Support/UltraStarDeluxe/Resources. 
+  This is where a user can add songs, themes, ....
+}
       function  GetGameUserPath   : WideString; override;
   end;
 
 implementation
 
 uses
+{ Used from SysUtils:
+  Types
+    TSearchRec
+  Constants
+    faAnyFile
+  Functions and Procedures
+    DirectoryExists
+    ExtractFilePath
+    FileGetAttr
+    FileExists
+    FindFirst
+    FindNext
+    FindClose
+    GetEnvironmentVariable
+}
   SysUtils,
-  baseunix;
+  
+{ Used from BaseUnix:
+  Types
+    pdir
+    pDirent
+  Functions and Procedures
+    FPOpenDir
+    FPReadDir
+    FPCloseDir
+}
+  BaseUnix;
 
 procedure TPlatformMacOSX.Init;
 begin
@@ -77,29 +152,65 @@ end;
 
 procedure TPlatformMacOSX.CreateUserFolders();
 var
-  RelativePath, BaseDir, OldBaseDir: string;
+{ } 
+  RelativePath, 
+{ BaseDir contains the path to the folder, where a search is performed.
+  It is set to the entries in @link(DirectoryList) one after the other.
+}
+  BaseDir, 
+{ OldBaseDir contains the path to the folder, where the search started.
+  It is used to return to it, when the search is completed in all folders.
+}
+  OldBaseDir: string;
+{ This record contains the result of a file search with FindFirst or FindNext}
   SearchInfo: TSearchRec;
+{ These two lists contain all folder and file names found
+  within the folder @link(BaseDir).
+}
   DirectoryList, FileList: TStringList;
+{ DirectoryIsFinished contains the index of the folder in @link(DirectoryList),
+  which is the last one completely searched. Later folders are still to be 
+  searched for additional files and folders.
+}
   DirectoryIsFinished: longint;
   counter: longint;
 
   UserPathName: string;
+{ SourceFile and TaretFile are used to copy a file from on folder to another. }
   SourceFile, TargetFile: TFileStream;
+{ FileCopyBuffer is the buffer for copying @link(SourceFile) to @link(TargetFile).
+  Its size (4096) has been choosen with little testing. A smaller size makes 
+  copying slower. A larger size may make copying large files faster.
+}
   FileCopyBuffer: array [1..4096] of byte;
+{ NumberOfBytes is the number of bytes read from @link(SourceFile) }
   NumberOfBytes: integer;
 const
+{ This string is used to construct the @link(UserPathName) }
   PathName: string = '/Library/Application Support/UltraStarDeluxe/Resources';
 begin
+{ Get the current folder and save it in OldBaseDir for returning to it, when 
+  finished.
+}
   getdir (0, OldBaseDir);
+{ UltraStarDeluxe.app/Contents/Resources contains all the default files and 
+  folders. 
+}
   BaseDir := OldBaseDir + '/UltraStarDeluxe.app/Contents/Resources';
   chdir (BaseDir);
+{ Right now, only $HOME/Library/Application Support/UltraStarDeluxe/Resources
+  is used.
+}
   UserPathName := GetEnvironmentVariable('HOME') + PathName;
 
   DirectoryIsFinished := 0;
   DirectoryList := TStringList.Create();
   FileList := TStringList.Create();
   DirectoryList.Add('.');
+  
+{ create the folder and file lists }
   repeat
+
     RelativePath := DirectoryList[DirectoryIsFinished];
     chdir (BaseDir + '/' + RelativePath);
     if (FindFirst('*', faAnyFile, SearchInfo) = 0) then
@@ -118,6 +229,7 @@ begin
     DirectoryIsFinished := succ(DirectoryIsFinished);
   until (DirectoryIsFinished = DirectoryList.Count);
 
+{ create missing folders }
   if not DirectoryExists(UserPathName) then
     mkdir (UserPathName);
 
@@ -126,6 +238,7 @@ begin
       mkdir (UserPathName + '/' + DirectoryList[counter]);
   DirectoryList.Free();
 
+{ copy missing files }
   for counter := 0 to Filelist.Count-1 do
     if not FileExists(UserPathName + '/' + Filelist[counter]) then
     begin
@@ -140,13 +253,14 @@ begin
     end;
   FileList.Free();
 
+{ go back to the initial folder }
   chdir (OldBaseDir);
 end;
 
-// Mac applications are packaged in directories.
-// We have to cut the last two directories
-// to get the application directory.
-
+{ Mac applications are packaged in folders.
+  We have to cut the last two folders
+  to get the application folder.
+}
 function TPlatformMacOSX.GetBundlePath: WideString;
 var
   i, pos : integer;
@@ -171,19 +285,16 @@ end;
 
 function TPlatformMacOSX.GetLogPath: WideString;
 begin
-  // eddie: Please read the note at the top of this file, why we use the application directory and not the user directory.
   Result := GetApplicationSupportPath + 'Logs';
 end;
 
 function TPlatformMacOSX.GetGameSharedPath: WideString;
 begin
-  // eddie: Please read the note at the top of this file, why we use the application directory and not the user directory.
   Result := GetApplicationSupportPath;
 end;
 
 function TPlatformMacOSX.GetGameUserPath: WideString;
 begin
-  // eddie: Please read the note at the top of this file, why we use the application directory and not the user directory.
   Result := GetApplicationSupportPath;
 end;