Doxygen comments part 2 - c files

src/Bitmaps.c

@@ -1,30 +1,65 @@
 // Copyright (c) Jon Thysell <http://jonthysell.com>
 // Licensed under the MIT License.
 
+/**
+ * @file Bitmaps.c
+ *
+ * This file provides implementations for Bitmaps.h.
+ */
+
 #include <OSUtils.h>
 
 #include "Bitmaps.h"
 
+/** The first PICT resource ID. */
 #define BasePictResID        BaseResID
 
+/** Index of the title PICT resource ID. */
 #define TitlePictResID       0
+
+/** Starting index of the number character PICT resource IDs. */
 #define NumCharPictBaseResID (TitlePictResID + 1)
+
+/** Index of the A character PICT resource ID. */
 #define ACharPictResID       (NumCharPictBaseResID + NumCharPictCount)
+
+/** Index of the B character PICT resource ID. */
 #define BCharPictResID       (ACharPictResID + 1)
+
+/** Index of the / character PICT resource ID. */
 #define SlashCharPictResID   (BCharPictResID + 1)
+
+/** Starting index of the star PICT resource IDs. */
 #define StarPictBaseResID    (SlashCharPictResID + 1)
+
+/** Index of the previous button PICT resource ID. */
 #define PrevButtonPictResID  (StarPictBaseResID + StarPictCount)
+
+/** Index of the next button PICT resource ID. */
 #define NextButtonPictResID  (PrevButtonPictResID + 1)
+
+/** Index of the retry button PICT resource ID. */
 #define RetryButtonPictResID (NextButtonPictResID + 1)
+
+/** Index of the sound off PICT resource ID. */
 #define SoundOffPictResID    (RetryButtonPictResID + 1)
+
+/** Index of the sound on PICT resource ID. */
 #define SoundOnPictResID     (SoundOffPictResID + 1)
+
+/** Index of the light off PICT resource ID. */
 #define LightOffPictResID    (SoundOnPictResID + 1)
+
+/** Index of the light on PICT resource ID. */
 #define LightOnPictResID     (LightOffPictResID + 1)
 
+/** The total number of PICT resources. */
 #define TotalPictCount       (LightOnPictResID + 1)
 
+/** Amount of padding to place between star PICTs. */
 #define StarRectPadding      2
 
+/** Mapping of months to the day of the year of their first day. */
 const int16_t MonthOffset[] = {
     0,   // Jan
     31,  // Feb
@@ -40,9 +75,19 @@ const int16_t MonthOffset[] = {
     335, // Dec
 };
 
+/**
+ * Gets the override base resource ID.
+ * @return The base resource ID.
+ */
 int16_t Bitmaps_GetOverrideBaseResID();
 
-PicHandle Bitmaps_GetPict(const int16_t holidayResID, const int16_t offset);
+/**
+ * Gets the PICT specified by the base resource ID and given offset.
+ * @param baseResID The base resource ID.
+ * @param offset The offset.
+ * @return The PICT resource.
+ */
+PicHandle Bitmaps_GetPict(const int16_t baseResID, const int16_t offset);
 
 void Bitmaps_Init(Bitmaps *pBitmaps)
 {

src/Common.h

@@ -32,6 +32,6 @@
 #define bitToggle(value, bit) ((value) ^= (1UL << (bit)))
 
 /** Sets the bit within value to bitValue. */
-#define bitWrite(value, bit, bitValue) ((bitBalue) ? bitSet(value, bit) : bitClear(value, bit))
+#define bitWrite(value, bit, bitValue) ((bitValue) ? bitSet(value, bit) : bitClear(value, bit))
 
 #endif

src/GameEndScene.c

@@ -1,9 +1,18 @@
 // Copyright (c) Jon Thysell <http://jonthysell.com>
 // Licensed under the MIT License.
 
+/**
+ * @file GameEndScene.c
+ *
+ * This file provides implementations for GameEndScene.h.
+ */
+
 #include "GameEndScene.h"
 
+/** Scale factor for the A/B set text. */
 #define SetTextScale   6
+
+/** Scale factor for the score text. */
 #define ScoreTextScale 3
 
 void GameEndScene_Init(GameWindow *pGameWindow)

src/GameEngine.c

@@ -1,6 +1,12 @@
 // Copyright (c) Jon Thysell <http://jonthysell.com>
 // Licensed under the MIT License.
 
+/**
+ * @file GameEngine.c
+ *
+ * This file provides implementations for GameEngine.h.
+ */
+
 #include "Common.h"
 #include "GameEngine.h"
 
@@ -12,8 +18,28 @@ const uint8_t MinHalfStars = 1;
 
 const uint16_t PerfectScore = 300; // LevelCount * MaxHalfStars
 
+/**
+ * Loads the given level as the current level.
+ * @param level The level.
+ * @param setB The set.
+ */
 void GameEngine_LoadLevel(GameEngine *pGameEngine, const int8_t level, const bool setB);
+
+/**
+ * Gets the number of half-stars to award given the par for the level, and the
+ * number of moves already taken.
+ * @param par The par for the level.
+ * @param moves The number of moves.
+ * @return The number of half-stars.
+ */
 uint8_t GameEngine_CalculateHalfStars(const uint16_t par, const uint16_t moves);
+
+/**
+ * Toggles the single light at the given coordinates.
+ * @param pGameEngine The GameEngine.
+ * @param x The x coordinate of the light.
+ * @param y The y coordinate of the light.
+ */
 void GameEngine_ToggleSingleLight(GameEngine *pGameEngine, const int8_t x, const int8_t y);
 
 void GameEngine_Init(GameEngine *pGameEngine)

src/GameWindow.c

@@ -1,6 +1,12 @@
 // Copyright (c) Jon Thysell <http://jonthysell.com>
 // Licensed under the MIT License.
 
+/**
+ * @file GameWindow.c
+ *
+ * This file provides implementations for GameWindow.h.
+ */
+
 #include "GameWindow.h"
 #include "TitleScene.h"
 #include "LevelSelectScene.h"

src/LevelEndScene.c

@@ -1,10 +1,21 @@
 // Copyright (c) Jon Thysell <http://jonthysell.com>
 // Licensed under the MIT License.
 
+/**
+ * @file LevelEndScene.c
+ *
+ * This file provides implementations for LevelEndScene.h.
+ */
+
 #include "LevelEndScene.h"
 
+/** Scale factor for the level text. */
 #define LevelTextScale 4
+
+/** Scale factor for the stars. */
 #define HalfStarScale  3
+
+/** Scale factor for score text. */
 #define ScoreTextScale 1
 
 void LevelEndScene_Init(GameWindow *pGameWindow)

src/LevelSelectScene.c

@@ -1,19 +1,49 @@
 // Copyright (c) Jon Thysell <http://jonthysell.com>
 // Licensed under the MIT License.
 
+/**
+ * @file LevelSelectScene.c
+ *
+ * This file provides implementations for LevelSelectScene.h.
+ */
+
 #include "LevelSelectScene.h"
 
+/** Scale factor for the A/B set text. */
 #define SetTextScale   3
+
+/** Scale factor for the score text. */
 #define ScoreTextScale 1
 
+/** Margin for each level selection. */
 #define LevelMargin         10
+
+/** Width for each level selection. */
 #define LevelWidth          80
+
+/** Height for each level selection. */
 #define LevelHeight         60
+
+/** The number of rows of levels to show. */
 #define LevelRowCount       2
+
+/** The number of columns of levels to show. */
 #define LevelColumnCount    5
+
+/** The total number of levels to show per page.  */
 #define LevelsPerPage       (LevelRowCount * LevelColumnCount)
+
+/** Scale factor for the level text. */
 #define LevelTextScale      1
 
+/**
+ * Gets the Rect of the level selection at the given index.
+ * @param pGameWindow The GameWindow.
+ * @param pRect. The Rect of the level selection.
+ * @param i The index of the level onscreen.
+ */
+void LevelSelectScene_SetLevelRect(const GameWindow *pGameWindow, Rect *pRect, const int8_t i);
+
 void LevelSelectScene_Init(GameWindow *pGameWindow)
 {
     Rect r;

src/Levels.c

@@ -1,9 +1,16 @@
 // Copyright (c) Jon Thysell <http://jonthysell.com>
 // Licensed under the MIT License.
 
+/**
+ * @file Levels.c
+ *
+ * This file provides implementations for Levels.h.
+ */
+
 #include "Common.h"
 #include "Levels.h"
 
+/** The levels from Set A, stored in 32-bit integers. */
 const uint32_t Levels_LightsA[] = {
     0x0005400UL, 0x15A82B5UL, 0x0ADEF6AUL, 0x1B88360UL, 0x1BC5EEFUL, 0x0EAD400UL, 0x0F8C62FUL, 0x0AAA880UL, 0x07D3BEAUL,
     0x00039CEUL, 0x0EAD6B5UL, 0x0A76D5FUL, 0x022AA88UL, 0x0210800UL, 0x0010040UL, 0x1F08421UL, 0x1F71000UL, 0x0455544UL,
@@ -13,6 +20,7 @@ const uint32_t Levels_LightsA[] = {
     0x0477DC4UL, 0x10917E4UL, 0x0089220UL, 0x1151151UL, 0x1FFFFFFUL,
 };
 
+/** The levels from Set B, stored in 32-bit integers. */
 const uint32_t Levels_LightsB[] = {
     0x1B06C1BUL, 0x1F2009FUL, 0x1F5115FUL, 0x11D822AUL, 0x0466CC4UL, 0x0AFD7EAUL, 0x158EE35UL, 0x0013800UL, 0x0531110UL,
     0x11AC6A0UL, 0x1F739DFUL, 0x1150151UL, 0x0E4394EUL, 0x093BD2FUL, 0x0EAD6B5UL, 0x0E4384EUL, 0x1F8D63FUL, 0x1505415UL,

src/MacCommon.c

@@ -1,11 +1,21 @@
 // Copyright (c) Jon Thysell <http://jonthysell.com>
 // Licensed under the MIT License.
 
+/**
+ * @file MacCommon.c
+ *
+ * This file provides implementations for MacCommon.h.
+ */
+
 #include "MacCommon.h"
 
+/** Resource ID for the error alert. */
 #define ErrorAlertResID  BaseResID
+
+/** Resource ID for the confirm alert. */
 #define ConfirmAlertResID (ErrorAlertResID + 1)
 
+/** Item ID for a Yes result from the confirm alert. */
 #define ConfirmYesResult 2
 
 void ShowError(Str255 message, bool isFatal)

src/MacLO.c

@@ -1,35 +1,95 @@
 // Copyright (c) Jon Thysell <http://jonthysell.com>
 // Licensed under the MIT License.
 
+/**
+ * @file MacLO.c
+ *
+ * This file provides implementations for MacLO.h.
+ */
+
 #include "GameWindow.h"
 #include "MacLO.h"
 
+/** Resource ID for the apple menu. */
 #define AppleMenuResID     BaseResID
+
+/** Resource ID for the about menu item. */
 #define AboutMenuItemID    1
 
+/** Resource ID for the game menu. */
 #define GameMenuResID      BaseResID+1
+
+/** Resource ID for the title menu id. */
 #define TitleMenuItemID    1
+
+/** Resource ID for the clear menu id. */
 #define ClearMenuItemID    2
+
+/** Resource ID for the quit menu id. */
 #define QuitMenuItemID     4
 
+/** Resource ID for the about dialog. */
 #define AboutDialogResID   BaseResID
+
+/** Resource ID for the about dialog's ok button. */
 #define AboutDialogOKID    1
 
+/** GameWindow global instance. */
 GameWindow gGameWindow;
-Boolean gExitApp;
 
+/** Bool to signal that the app should exit. */
+bool gExitApp;
+
+/**
+ * Processes the update event with the given EventRecord.
+ * @param pEvent The EventRecord. 
+ */
 void MacLO_HandleUpdate(const EventRecord *pEvent);
+
+/**
+ * Processes the mouse down event with the given EventRecord.
+ * @param pEvent The EventRecord. 
+ */
 void MacLO_HandleMouseDown(const EventRecord *pEvent);
+
+/**
+ * Processes the mouse up event with the given EventRecord.
+ * @param pEvent The EventRecord. 
+ */
 void MacLO_HandleMouseUp(const EventRecord *pEvent);
 
+/**
+ * Processes when a menu has been selected.
+ * @param menuChoice The menu selected.
+ */
 void MacLO_HandleMenuChoice(const int32_t menuChoice);
+
+/**
+ * Processes when an item was selected in the apple menu.
+ * @param item The item in the menu selected.
+ */
 void MacLO_HandleAppleMenuChoice(const int16_t item);
 
+/**
+ * Shows the about dialog.
+ */
 void MacLO_ShowAboutDialog();
+
+/**
+ * Launches the item selected in the apple menu.
+ * @param item The item in the menu selected.
+ */
 void MacLO_LaunchAppleMenuItem(const int16_t item);
 
+/**
+ * Processes when an item was selected in the game menu.
+ * @param item The item in the menu selected.
+ */
 void MacLO_HandleGameMenuChoice(const int16_t item);
 
+/**
+ * Quits the application.
+ */
 void MacLO_Quit();
 
 void MacLO_ToolBoxInit()

src/PlayScene.c

@@ -1,21 +1,48 @@
 // Copyright (c) Jon Thysell <http://jonthysell.com>
 // Licensed under the MIT License.
 
+/**
+ * @file PlayScene.c
+ *
+ * This file provides implementations for PlayScene.h.
+ */
+
 #include "PlayScene.h"
 
+/** Margin around the Playfield area. */
 #define PlayfieldMargin     4
-#define PlayfieldPadding    2
-#define PlayfieldCornerSize 12
-#define LightMargin         6
-#define LightSize           50
-#define LightCornerSize     12
 
+/** Padding within the Playfield area. */
+#define PlayfieldPadding    2
+
+/** Corner size of the Playfield area. */
+#define PlayfieldCornerSize 12
+
+/** Margin around each light. */
+#define LightMargin         6
+
+/** Size (width and height) of each light. */
+#define LightSize           50
+
+/** Margin around the HUD area. */
 #define HUDMargin PlayfieldMargin
 
+/** Scale factor for the level text. */
 #define LevelTextScale 3
+
+/** Scale factor for the stars. */
 #define HalfStarScale  2
+
+/** Scale factor for the score text. */
 #define ScoreTextScale 1
 
+/**
+ * Gets the Rect of the light at the given coordinates.
+ * @param pGameWindow The GameWindow.
+ * @param pRect. The Rect of the light.
+ * @param c The column.
+ * @param r The row.
+ */
 void PlayScene_SetLightRect(const GameWindow *pGameWindow, Rect *pRect, const int8_t c, const int8_t r);
 
 void PlayScene_Init(GameWindow *pGameWindow)

src/Sounds.c

@@ -1,15 +1,30 @@
 // Copyright (c) Jon Thysell <http://jonthysell.com>
 // Licensed under the MIT License.
 
+/**
+ * @file Sounds.c
+ *
+ * This file provides implementations for Sounds.h.
+ */
+
 #include "Sounds.h"
 
+/** The first snd resource ID. */
 #define SndBaseResId  8192
 
+/** The click snd resource ID. */
 #define ClickSndResID SndBaseResId
+
+/** The retry snd resource ID. */
 #define RetrySndResID (ClickSndResID + 1)
+
+/** The done snd resource ID. */
 #define DoneSndResID  (RetrySndResID + 1)
 
+/** Whether or not sound is enabled by default. */
 #define DefaultEnabled  true
+
+/** Whether or not to play sound async. */
 #define PlaySoundsAsync false
 
 void Sounds_Init(Sounds *pSounds)

src/TitleScene.c

@@ -1,9 +1,16 @@
 // Copyright (c) Jon Thysell <http://jonthysell.com>
 // Licensed under the MIT License.
 
+/**
+ * @file TitleScene.c
+ *
+ * This file provides implementations for TitleScene.h.
+ */
+
 #include "TitleScene.h"
 #include "Bitmaps.h"
 
+/** Scale factor for the text. */
 #define TitleTextScale 2
 
 void TitleScene_Init(GameWindow *pGameWindow)

src/WindowBuffer.c

@@ -1,6 +1,12 @@
 // Copyright (c) Jon Thysell <http://jonthysell.com>
 // Licensed under the MIT License.
 
+/**
+ * @file WindowBuffer.c
+ *
+ * This file provides implementations for WindowBuffer.h.
+ */
+
 #include "WindowBuffer.h"
 #include "MacCommon.h"
 

src/main.c

@@ -1,8 +1,17 @@
 // Copyright (c) Jon Thysell <http://jonthysell.com>
 // Licensed under the MIT License.
 
+/**
+ * @file main.c
+ *
+ * This file provides the main() entry point.
+ */
+
 #include "MacLO.h"
 
+/**
+ * Entry point for the application.
+ */
 void main(void)
 {
     MacLO_ToolBoxInit();