Improve documentation

include/basic.h

@@ -13,10 +13,12 @@
  * @brief Basic object.
  *
  * Base class for most objects.
+ *
+ * @todo Declare virtual methods.
  */
 struct BASIC
 {
-    int field_0x0;
+    int field_0x0; // placeholder for vtable
     CSidebag *psidebag;
 };
 

include/binoc.h

@@ -10,7 +10,7 @@
 
 /**
  * @brief Horizontal text justification.
-*/
+ */
 typedef enum JH
 {
     JH_Nil = -1,
@@ -22,7 +22,7 @@ typedef enum JH
 
 /**
  * @brief Vertical text justification.
-*/
+ */
 typedef enum JV
 {
     JV_Nil = -1,
@@ -34,7 +34,7 @@ typedef enum JV
 
 /**
  * @brief RGBA color value.
-*/
+ */
 struct RGBA
 {
     uchar bRed;
@@ -54,20 +54,51 @@ struct RGBA
 class CTextBox
 {
 public:
+    /**
+     * @brief Sets the position of the text box.
+     *
+     * @param x X position.
+     * @param y Y position.
+     */
     void SetPos(float x, float y);
+
+    /**
+     * @brief Sets the size of the text box.
+     *
+     * @param dx Width.
+     * @param dy Height.
+     */
     void SetSize(float dx, float dy);
-    void SetTextColor(RGBA* rgba);
+
+    /**
+     * @brief Sets the text color.
+     *
+     * @param rgba RGBA color value.
+     */
+    void SetTextColor(RGBA *rgba);
+
+    /**
+     * @brief Sets the horizontal text justification.
+     *
+     * @param jh Horizontal text justification.
+     */
     void SetHorizontalJust(JH jh);
+
+    /**
+     * @brief Sets the vertical text justification.
+     *
+     * @param jv Vertical text justification.
+     */
     void SetVerticalJust(JV jv);
 
 private:
-    float m_x;
-    float m_y;
-    float m_dx;
-    float m_dy;
-    RGBA m_rgba;
-    enum JH m_jh;
-    enum JV m_jv;
+    float m_x;    // X position.
+    float m_y;    // Y position.
+    float m_dx;   // Width.
+    float m_dy;   // Height.
+    RGBA m_rgba;  // Text color.
+    enum JH m_jh; // Horizontal text justification.
+    enum JV m_jv; // Vertical text justification;
 };
 
 #endif /* BINOC_H */

include/bis.h

@@ -165,8 +165,6 @@ public:
      */
     void Align(int n);
 
-    // MARK: Read Methods
-
     /**
      * @brief Reads a byte from the stream.
      *

include/cat.h

@@ -8,16 +8,22 @@
 
 #include "common.h"
 
+/**
+ * @brief Related to file location.
+ */
 struct FCL
 {
     uint isector;
     uint cb;
 };
 
+/**
+ * @brief File location.
+ */
 class CFileLocation
 {
 public:
-    FCL fcl;
+    FCL fcl; // File sector and size.
 };
 
 #endif // CAT_H

include/chkpnt.h

@@ -15,8 +15,6 @@
  * @brief Checkpoint.
  *
  * @todo Define struct.
- *
- * @note CHKPNT : ALO : LO : BASIC
  */
 struct CHKPNT : public ALO
 {
@@ -24,13 +22,15 @@ struct CHKPNT : public ALO
 };
 
 /**
- * @brief Checkpoint Manager
+ * @brief Checkpoint Manager.
+ *
+ * @todo Fill in missing fields.
  */
 struct CHKMGR
 {
-	int cbitChk;
-	int unk_0x8;
-	int padding[128];
+	int cbitChk; // Count of values in abitChk.
+	int *abitChk; // Unknown, name/type may be wrong.
+	int padding[128]; // Temporary padding
 	int fChkDirty;
 	VECTOR posVolChkpnt;
 	int csSaved[129]; // type may be wrong

include/cid.h

@@ -10,6 +10,8 @@
 
 /**
  * @brief Class ID.
+ *
+ * @note Values are based on May 19 build, and may not be accurate to release.
  */
 enum CID
 {

include/cm.h

@@ -16,7 +16,7 @@
 struct CM; // Forward declaration
 
 /**
- * @brief Unknown.
+ * @brief Unknown Kind.
  */
 enum CFK
 {
@@ -198,7 +198,7 @@ struct CPASEG : public CPLCY
  *
  * Unknown usage.
  *
- * @note Might be unused in the final game based on the name.
+ * @note Might be unused in release build, based on the name.
  */
 struct CPTN : public CPLCY
 {

include/difficulty.h

@@ -5,6 +5,7 @@
  */
 #ifndef DIFFICULTY_H
 #define DIFFICULTY_H
+
 #include "common.h"
 #include <util.h>
 #include <chkpnt.h>

include/find.h

@@ -11,6 +11,14 @@
 #include <sw.h>
 #include <cid.h>
 
+/**
+ * @brief Gets the DL for the SW object with the given OID.
+ *
+ * @param psw The SW object.
+ * @param oid The OID of the object.
+ *
+ * @return The DL for the object, or NULL if the object was not found.
+ */
 DL *PdlFromSwOid(SW *psw, OID oid);
 
 void MatchSwObject(LO *ploMatch, int grffsoMask, int fIncludeRemoved, int fProxyMatch, LO *ploContext, int cploMax, int *pcploMatch, LO **aplo, int *pcpaloBest);
@@ -23,12 +31,29 @@ LO *PloFindSwNearest(SW *psw, OID oid, LO *ploContext);
 
 LO *PloFindSwChild(SW *psw, OID oid, ALO *paloAncestor);
 
+/**
+ * @brief Checks if the given CID is derived from another.
+ *
+ * @param cid The CID to check.
+ * @param cidAncestor The CID to check against.
+ *
+ * @retval 1 if the CID is derived from the ancestor.
+ * @retval 0 if the CID is not derived from the ancestor.
+ */
 int FIsCidDerivedFrom(int cid, int cidAncestor);
 
 int CploFindSwObjectsByClass(SW *psw, int grffso, CID cid, LO *ploContext, int cploMax, LO **aplo);
 
 LO *PloFindSwObjectByClass(SW *psw, int grffso, CID cid, LO *ploContext);
 
+/**
+ * @brief Finds the common parent of two LOs.
+ *
+ * @param plo The first LO.
+ * @param ploOther The second LO.
+ *
+ * @return The common parent of the two LOs.
+ */
 ALO *PaloFindLoCommonParent(LO *plo, LO *ploOther);
 
 #endif // FIND_H

include/flash.h

@@ -12,6 +12,9 @@
 #include <shd.h>
 #include <cm.h>
 
+/**
+ * @brief Unknown.
+ */
 struct RO
 {
     MATRIX4 mat;
@@ -38,12 +41,36 @@ struct FLASH : public ALO
     undefined4 unk2;
 };
 
+/**
+ * @brief Initializes the given flash.
+ *
+ * @param pflash Flash to initialize.
+ */
 void InitFlash(FLASH *pflash);
 
+/**
+ * @brief Loads a flash from the given binary input stream.
+ *
+ * @param pflash Where to load the flash.
+ * @param pbis Binary input stream.
+ */
 void LoadFlashFromBrx(FLASH *pflash, CBinaryInputStream *pbis);
 
+/**
+ * @brief Updates the given flash.
+ *
+ * @param pflash Flash to update.
+ * @param dt Delta time.
+ */
 void UpdateFlash(FLASH *pflash, float dt);
 
+/**
+ * @brief Renders the given flash.
+ *
+ * @param pflash Flash to render.
+ * @param pcm Game camera.
+ * @param pro Render options(?).
+ */
 void RenderFlashSelf(FLASH *pflash, CM *pcm, RO *pro);
 
 int FPosFlashWithin(FLASH *pflash, VECTOR *ppos);

include/fly.h

@@ -1,7 +1,7 @@
 /**
  * @file fly.h
  *
- * @brief Fly critters.
+ * @brief Flies.
  */
 #ifndef FLY_H
 #define FLY_H

include/font.h

@@ -8,6 +8,9 @@
 
 #include "common.h"
 
+/**
+ * @brief Scaled font ratio.
+ */
 struct SFR
 {
     float rx, ry;

include/rat.h

@@ -0,0 +1,13 @@
+/**
+ * @file rat.h
+ *
+ * @brief Rats.
+ */
+#ifndef RAT_H
+#define RAT_H
+
+#include "common.h"
+
+// ...
+
+#endif // RAT_H