Merge pull request #46 from TheOnlyZac/theonlyzac-doxygen

Prepare codebase for documentation generation with Doxygen

.github/workflows/generate_docs.yml

@@ -0,0 +1,43 @@
+name: Generate Doxygen Documentation
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  update-gh-pages:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout main branch
+        uses: actions/checkout@v2
+        with:
+          ref: main
+
+      - name: Switch to gh-pages branch
+        run: git checkout gh-pages
+        continue-on-error: false
+
+      - name: Init submodules
+        run: git submodule update --init --recursive
+
+      - name: Clone main branch into working dir
+        run: git clone https://github.com/${{ github.repository }} --branch main sly1
+
+      - name: Remove old docs
+        run: rm -rf ./html
+
+      - name: Run doxygen
+        run: doxygen Doxyfile
+
+      - name: Remove cloned project dir
+        run: rm -rf ./sly1
+
+      - name: Commit and push changes to gh-pages
+        run: |
+          git config --global user.name "${{ github.actor }}"
+          git config --global user.email "${{ github.actor }}@users.noreply.github.com"
+          git add .
+          git commit -m "Generate doxygen documentation"
+          git push origin gh-pages

src/P2/actseg.h

@@ -1,9 +1,14 @@
+/**
+ * @file actseg.h
+ *
+ * @brief Declarations for actor segments.
+*/
 #pragma once
 #include <vec.h>
 #include <util.h>
 
 /**
- * Unknown
+ * @brief Unknown, needs more research
 */
 struct ACTLA
 {

src/P2/alarm.h

@@ -1 +1,6 @@
+/**
+ * @file alarm.h
+ *
+ * @brief Declarations for the alarm system.
+*/
 #pragma once

src/P2/alo.h

@@ -1,3 +1,6 @@
+/**
+ * @file alo.h
+*/
 #pragma once
 
 struct ALO {

src/P2/aseg.h

@@ -1,9 +1,14 @@
+/**
+ * @file aseg.h
+ *
+ * @brief Declarations for animation segments.
+*/
 #pragma once
 #include <util.h>
 #include <game.h>
 
 /**
- * Animation Segment
+ * @brief Animation Segment
 */
 struct ASEG
 {

src/P2/bas.cpp

@@ -1,3 +1,8 @@
+/**
+ * @file bas.cpp
+ *
+ * @brief Implements for the binary async stream class.
+*/
 #include <bas.h>
 #include <cstddef>
 

src/P2/bas.h

@@ -1,9 +1,14 @@
+/**
+ * @file bas.h
+ *
+ * @brief Declarations for the binary async stream.
+*/
 #pragma once
 #include <stdint.h>
 #include <util.h>
 
 /**
- * Binary Async Stream Kind
+ * @brief Binary Async Stream Kind
 */
 enum BASK : int
 {
@@ -14,7 +19,7 @@ enum BASK : int
 };
 
 /**
- * Binary Async Stream
+ * @brief Binary Async Stream
 */
 class CBinaryAsyncStream
 {

src/P2/basic.h

@@ -1,3 +1,8 @@
+/**
+ * @file basic.h
+ *
+ * @brief Declares the BASIC struct.
+*/
 #pragma once
 
 struct BASIC

src/P2/bis.cpp

@@ -1,3 +1,8 @@
+/**
+ * @file bis.h
+ *
+ * @brief Implements the binary input stream class.
+*/
 #include <bis.h>
 
 CBinaryInputStream::CBinaryInputStream(std::string fileName)

src/P2/bis.h

@@ -1,3 +1,8 @@
+/**
+ * @file bis.h
+ *
+ * @brief Declarations for the binary input stream.
+*/
 #pragma once
 #include <bas.h>
 #include <cat.h>
@@ -9,7 +14,7 @@
 typedef unsigned char byte; //todo move to util header
 
 /**
- * Binary Input Stream Kind
+ * @brief Binary Input Stream Kind
  *
  * Types of binary stream that can be opened
 */
@@ -23,7 +28,7 @@ enum BISK : int
 };
 
 /**
- * Binary Input Stream
+ * @brief Binary Input Stream
  *
  * Used to read binary data from files on the disc.
 */
@@ -257,4 +262,4 @@ class CBinaryInputStream
 };
 
 // Global variables
-static uint32_t g_fCdAvailable;
+static uint32_t g_fCdAvailable; // Is the CD available for reading?

src/P2/bq.h

@@ -1,7 +1,15 @@
+/**
+ * @file bq.h
+ *
+ * @brief Declares the byte queue class.
+*/
 #pragma once
 
 typedef unsigned char BYTE; //todo mode to util header
 
+/**
+ * @brief Byte Queue
+*/
 class CByteQueue {
     BYTE* m_ab;
     int m_cb;

src/P2/brx.cpp

@@ -1,4 +1,9 @@
-#include "brx.h"
+/**
+ * @file brx.cpp
+ *
+ * @brief Implements interaction with binary resource archives.
+*/
+#include <brx.h>
 
 SW* PloNew(CID cid, SW* csw, ALO* paloParent, OID oid, int isplice)
 {

src/P2/brx.h

@@ -1,3 +1,8 @@
+/**
+ * @file brx.h
+ *
+ * @brief Declarations for interaction with binary resource archives.
+*/
 #include <alo.h>
 #include <game.h>
 #include <sw.h>

src/P2/cat.cpp

@@ -1,3 +1,8 @@
+/**
+ * @file cat.cpp
+ *
+ * @brief Implements the WAC/WAL catalog system.
+*/
 #include "cat.h"
 #include <cstring>
 

src/P2/cat.h

@@ -1,10 +1,15 @@
+/**
+ * @file cat.h
+ *
+ * @brief Declarations for working with WAC and WAL catalogs.
+*/
 #pragma once
 #include <iostream>
 
 typedef unsigned int uint; //todo move to util header
 
 /**
- * File Location
+ * @brief File Location
  *
  * Stores the file location and size in bytes.
 */
@@ -15,7 +20,7 @@ struct FCL
 };
 
 /**
- * File Key
+ * @brief File Key
  *
  * Used to identify the file type.
 */
@@ -32,7 +37,7 @@ enum FK {
 };
 
 /**
- * WAL Entry
+ * @brief WAL Entry
  *
  * Stores the file key and file location & size.
 */
@@ -42,6 +47,8 @@ struct WALE {
 };
 
 /**
+ * @brief File Location
+ *
  * Handles information about the file sector and size.
 */
 class CFileLocation
@@ -53,6 +60,8 @@ class CFileLocation
 };
 
 /**
+ * @brief WAL Catalog
+ *
  * Handles the WAC and WAL files.
 */
 class CWalCatalog
@@ -117,6 +126,8 @@ class CWalCatalog
 };
 
 /**
+ * @brief Catalog
+ *
  * Related to the WAC and WAL files.
 */
 class CCatalog

src/P2/chkpnt.cpp

@@ -1,5 +1,9 @@
+/**
+ * @file chkpnt.cpp
+ *
+ * @brief Implements checkpoint methods.
+*/
 #include <chkpnt.h>
-
 #include <cstring>
 
 void ResetChkmgrCheckpoints(CHKMGR* pchkmgr)

src/P2/chkpnt.h

@@ -1,17 +1,22 @@
+/**
+ * @file chkpnt.h
+ *
+ * @brief Declarations for the checkpoint system.
+*/
 #pragma once
 #include <util.h>
 #include <game.h>
 #include <vec.h>
 
 /**
- * Checkpoint
+ * @brief Checkpoint
 */
 struct CHKPNT
 {
 };
 
 /**
- * Checkpoint Manager
+ * @brief Checkpoint Manager
 */
 struct CHKMGR
 {

src/P2/clock.cpp

@@ -1,13 +1,22 @@
+/**
+ * @file clock.cpp
+ *
+ * @brief Implements the game clock.
+*/
 #include <clock.h>
 
-/* Set magic numbers */
-static constexpr int CLOCK_FRAMERATE = 60;
-static constexpr float CLOCK_FRAMETIME = 1.f / CLOCK_FRAMERATE;
+/**
+ * Set magic numbers
+*/
+static constexpr int CLOCK_FRAMERATE = 60; // 60 FPS
+static constexpr float CLOCK_FRAMETIME = 1.f / CLOCK_FRAMERATE; // 1/60th of a second
 
-static constexpr int CLOCK_EE_TICK_RATE = 294912000;
-static constexpr float CLOCK_EE_TICK_DURATION = 1.f / CLOCK_EE_TICK_RATE;
+static constexpr int CLOCK_EE_TICK_RATE = 294912000; // 294.912 MHz
+static constexpr float CLOCK_EE_TICK_DURATION = 1.f / CLOCK_EE_TICK_RATE; // 1/294.912 MHz
 
-/* Init global/static vars */
+/**
+ * Init global/static vars
+*/
 float g_rtClock = 1.0;
 float g_trClockPowerUp = 1.0;
 CLOCK g_clock;

src/P2/clock.h

@@ -1,9 +1,14 @@
+/**
+ * @file clock.h
+ *
+ * @brief Declarations for the game clock.
+*/
 #pragma once
 
 typedef unsigned long long TICK;
 
 /**
- * Clock
+ * @brief Game Clock
 */
 struct CLOCK
 {
@@ -19,8 +24,8 @@ struct CLOCK
 };
 
 // Global variables
-extern CLOCK g_clock; // global game clock
-extern float g_rtClock;
+extern CLOCK g_clock; // Main game clock
+extern float g_rtClock; // Clock tick rate
 
 /**
  * @brief Sets the tick rate of the global clock.

src/P2/cm.cpp

@@ -1,3 +1,8 @@
+/**
+ * @file cm.cpp
+ *
+ * @brief Implements the game camera.
+*/
 #include <cm.h>
 
 CM* g_pcm = nullptr;
@@ -6,4 +11,4 @@ void SetupCm(CM* pcm)
 {
 	// todo
 	// ...
-}
+}