Add and clarify documentation comments

macos/error.h

@@ -7,40 +7,62 @@
 // Error codes, corresponding to messages in a STR# resource. This should be
 // kept in sync with STR# rSTRS_Errors in resources.r.
 typedef enum {
+	// An unknown error occurred.
 	kErrUnknown = 1,
+	// An internal error occurred.
 	kErrInternal,
+	// Out of memory.
 	kErrOutOfMemory,
+	// Could not save project "^1".
 	kErrCouldNotSaveProject,
 } ErrorCode;
 
-// Show an error dialog with the given error message, then quit the program.
+// ExitError shows an error dialog with the given error message, then quits the
+// program.
 void ExitError(ErrorCode errCode);
 
-// Show an error dialog with the given error message and an OS error code, then
-// quit the program.
+// ExitErrorOS shows an error dialog with the given error message and an OS
+// error code, then quits the program.
 void ExitErrorOS(ErrorCode errCode, short osErr);
 
-// Show an out of memory error and quit the program.
+// ExitMemError shows an out of memory error and quits the program.
 void ExitMemError(void);
 
-// Show an assertion error and quit the program.
+// ExitAssert shows an assertion error and quits the program. The message may be
+// NULL.
 void ExitAssert(const unsigned char *file, int line,
                 const unsigned char *message);
 
+// EXIT_ASSERT shows an assertion error and quits the program. The message may
+// be NULL.
 #define EXIT_ASSERT(str) ExitAssert("\p" __FILE__, __LINE__, str)
 
+// ASSERT checks that the given condition is true. Otherwise, it displays an
+// error message and quits the program.
 #define ASSERT(p)                                         \
 	do {                                                  \
 		if (!(p))                                         \
 			ExitAssert("\p" __FILE__, __LINE__, "\p" #p); \
 	} while (0)
 
+// An ErrorParams contains the parameters for displaying en error alert window.
+// This structure should be zeroed before use, in case additional fields are
+// added.
 struct ErrorParams {
+	// The application error code. If this is zero, it will be treated as
+	// kErrInternal.
 	ErrorCode err;
+
+	// The OS error code. This is displayed at the end of the error message,
+	// unless it is zero.
 	short osErr;
+
+	// If the error messages contain any string substitutions like "^1", those
+	// substitutions are replaced with this string.
 	const unsigned char *strParam;
 };
 
+// ShowError shows an error alert window to the user.
 void ShowError(const struct ErrorParams *p);
 
 #endif

macos/main.c

@@ -17,6 +17,7 @@ void QuitApp(void)
 	ExitToShell();
 }
 
+// HandleClose handles a request to close the given window.
 static void HandleClose(WindowRef window)
 {
 	ProjectHandle project;
@@ -33,6 +34,7 @@ static void HandleClose(WindowRef window)
 	}
 }
 
+// AdjustMenus adjusts menus before selecting a menu item.
 static void AdjustMenus(void)
 {
 	WindowRef window;
@@ -66,6 +68,8 @@ static void AdjustMenus(void)
 	}
 }
 
+// HandleMenuCommand handles a menu command. The top 16 bits store the menu ID,
+// and the low 16 bits store the item within that menu.
 static void HandleMenuCommand(long command)
 {
 	int menuID = command >> 16;
@@ -114,7 +118,7 @@ static void HandleMenuCommand(long command)
 	SysBeep(1);
 }
 
-// Handle a mouse down event.
+// HandleMouseDown handles a mouse down event.
 static void HandleMouseDown(EventRecord *event)
 {
 	short clickPart;
@@ -171,6 +175,7 @@ static void HandleMouseDown(EventRecord *event)
 	}
 }
 
+// HandleKeyDown handles a key down event.
 static void HandleKeyDown(EventRecord *event)
 {
 	long command;
@@ -183,6 +188,7 @@ static void HandleKeyDown(EventRecord *event)
 	}
 }
 
+// HandleActivate handles a window activate event.
 static void HandleActivate(EventRecord *event)
 {
 	ProjectHandle project;
@@ -204,6 +210,7 @@ static void HandleActivate(EventRecord *event)
 	SetPort(savedPort);
 }
 
+// HandleUpdate handles a window update event.
 static void HandleUpdate(EventRecord *event)
 {
 	ProjectHandle project;

macos/project.h

@@ -4,26 +4,26 @@
 #ifndef MACOS_PROJECT_H
 #define MACOS_PROJECT_H
 
-// Handle to a synchronization project.
+// A ProjectHandle is a handle to a synchronization project.
 typedef struct Project **ProjectHandle;
 
-// Create a new empty synchronization project.
+// ProjectNew creates a new empty synchronization project.
 void ProjectNew(void);
 
-// Adjust menus before selecting a menu item.
+// ProjectAdjustMenus adjusts menus before selecting a menu item.
 void ProjectAdjustMenus(ProjectHandle project, MenuHandle fileMenu);
 
-// Handle a menu command or equivalent.
+// ProjectCommand handles a menu command or equivalent.
 void ProjectCommand(WindowRef window, ProjectHandle project, int menuID,
                     int item);
 
-// Handle an update event for a project window.
+// ProjectUpdate handles an update event for a project window.
 void ProjectUpdate(WindowRef window, ProjectHandle project);
 
-// Set whether a project window is active.
+// ProjectActivate sets whether a project window is active.
 void ProjectActivate(WindowRef window, ProjectHandle project, int isActive);
 
-// Handle a mouse down event in a window.
+// ProjectMouseDown handles a mouse down event in a window.
 void ProjectMouseDown(WindowRef window, ProjectHandle project,
                       EventRecord *event);
 

macos/strutil.h

@@ -4,21 +4,21 @@
 #ifndef MACOS_STRUTIL_H
 #define MACOS_STRUTIL_H
 
-// Write a formatted string.
+// StrFormat writes a formatted string to another string, replacing it.
 void StrFormat(unsigned char *dest, const unsigned char *msg, ...);
 
-// Append a formatted string to another string.
+// StrAppend appends a formatted string to another string.
 //
 // %% - literal %
 // %d - int argument
 // %S - Pascal string argument
 void StrAppendFormat(unsigned char *dest, const unsigned char *msg, ...);
 
-// Copy a Pascal string. Aborts the program if the string does not fit in the
-// destination buffer.
+// StrCopy copies a Pascal string. Aborts the program if the string does not fit
+// in the destination buffer.
 void StrCopy(unsigned char *dest, int dest_size, unsigned char *src);
 
-// Substitute ^1 in the string with param.
+// StrSubstitute substitute ^1 in the string with param.
 void StrSubstitute(unsigned char *str, const unsigned char *param);
 
 #endif