document game.h

1 files changed, 74 insertions, 33 deletions

diff --git a/include/main.h b/include/main.h
index 7b0abd05..f7ab29c4 100644
--- a/include/main.h
+++ b/include/main.h
@@ -3,11 +3,16 @@
 
 #include "global.h"
 
+/** File signature */
 #define SIGNATURE 'MCZ3'
+/** Maximum message speed. */
 #define MAX_MSG_SPEED 3
+/** Number of save slots */
 #define NUM_SAVE_SLOTS 3
+/** Maximum brightness. */
 #define MAX_BRIGHTNESS 3
 
+/** Supported game languages. */
 typedef enum {
     LANGUAGE_JP,
     LANGUAGE_EN,
@@ -24,36 +29,44 @@ typedef enum {
 #define GAME_LANGUAGE LANGUAGE_JP
 #endif
 
-enum {
-    TASK_TITLE,
-    TASK_FILE_SELECT,
-    TASK_GAME,
-    TASK_GAMEOVER,
-    TASK_STAFFROLL,
-    TASK_DEBUG,
-};
-
-enum {
+/** Program tasks. */
+typedef enum {
+    TASK_TITLE,       /**< Title task. This is the first task to be entered. */
+    TASK_FILE_SELECT, /**< File selection task. */
+    TASK_GAME,        /**< Gameplay task. Overworld, menus, cutscenes are all contained here. */
+    TASK_GAMEOVER,    /**< Gameover task. */
+    TASK_STAFFROLL,   /**< Staffroll task. Only accessible through the script played during the game ending. */
+    TASK_DEBUG,       /**< Debug task. Inaccessible in normal gameplay. */
+} Task;
+
+/** System sleep status. */
+typedef enum {
     DEFAULT,
     SLEEP,
-};
+} SleepStatus;
 
+/**
+ * Main system structure.
+ */
 typedef struct {
     vu8 interruptFlag;
     u8 sleepStatus;
-    u8 task;
-    u8 state;
-    u8 substate;
+    u8 task;     /**< Current #Task. */
+    u8 state;    /**< State of the current #Task. */
+    u8 substate; /**< Substate of the current #Task. */
     u8 field_0x5;
-    u8 muteAudio;
+    u8 muteAudio; /**< Mute audio. */
     u8 field_0x7;
-    u8 pauseFrames;
-    u8 pauseCount;
-    u8 pauseInterval;
+    u8 pauseFrames;   /**< Number of frames to pause. */
+    u8 pauseCount;    /**< Number of pauses to make. */
+    u8 pauseInterval; /**< Number of frames to play between each pause. */
     u8 pad;
-    union SplitHWord ticks;
+    union SplitHWord ticks; /**< Current time. */
 } Main;
 
+/**
+ * HUD structure.
+ */
 typedef struct {
     /*0x00*/ u8 nextToLoad;
     /*0x01*/ u8 _1;
@@ -69,34 +82,62 @@ typedef struct {
 } UI;
 static_assert(sizeof(UI) == 0x3b4);
 
-extern Main gMain;
-extern UI gUnk_02032EC0;
+extern Main gMain;       /**< Main instance. */
+extern UI gUnk_02032EC0; /**< UI instance. */
 
 /**
- * @brief Begin a subroutine.
+ * Program entry point.
  */
-void SetTask(u32 screen);
+void AgbMain(void);
 
+/**
+ * Begin a new task.
+ *
+ * @param task #Task to begin.
+ */
+void SetTask(u32 task);
+
+/**
+ * Initialize the DMA system.
+ */
 void InitDMA(void);
 
-void sub_0805622C(void* a1, u32 a2, u32 a3);
+/**
+ * Soft reset the system.
+ */
+void DoSoftReset(void);
 
+/**
+ * Put the system into sleep mode.
+ */
+void SetSleepMode(void);
+
+extern void sub_0805622C(void* a1, u32 a2, u32 a3);
 extern void sub_08056208(void);
 extern void ResetPalettes(void);
-
-extern void DoSoftReset(void);
-extern void SetSleepMode(void);
 extern void VBlankIntrWait();
-extern void FadeMain(void);
-
-extern u8 gUnk_03003DE4;
-
-extern void SetBrightness(u32);
-extern u16 gPaletteBuffer[];
 extern void VBlankInterruptWait(void);
 extern void DisableInterruptsAndDMA(void);
 extern void EnableVBlankIntr(void);
 extern void sub_08056250(void);
 extern void sub_08056208(void);
 
+/** @name Task entrypoints */
+///@{
+/** Task entrypoint. */
+extern void TitleTask(void);
+extern void FileSelectTask(void);
+extern void GameTask(void);
+extern void GameOverTask(void);
+extern void StaffrollTask(void);
+extern void DebugTask(void);
+
+#ifdef DEMO_USA
+extern void DemoTask(void);
+#endif
+/// @}
+
+extern u8 gUnk_03003DE4;
+extern u16 gPaletteBuffer[];
+
 #endif