From a4414e3b79ce47443402812d9c4fae12079f351f Mon Sep 17 00:00:00 2001
From: Robin Jones <networkfusion@users.noreply.github.com>
Date: Sun, 16 Jul 2023 11:21:52 +0100
Subject: [PATCH] Improve code comments for doxygen (#14)

<!--- Provide a general summary of your changes in the Title above -->

## Description
<!--- Describe your changes in detail -->
Adds header file, strut and enum comments.
Fixes #ifndef `PAHT_H__` to be `#ifndef PATH_H__`

## Motivation and Context
<!--- What does this sample do? What problem does it solve? -->
<!--- If it fixes/closes/resolves an open issue, please link to the
issue here -->
works towards eliminating warnings with doxygen.

## How Has This Been Tested?
<!-- (if applicable) -->
<!--- Please describe in detail how you tested your sample/changes. -->
<!--- Include details of your testing environment, and the tests you ran
to -->
<!--- see how your change affects other areas of the code, etc. -->
Built within dev container.

## Screenshots
<!-- (if appropriate): -->

## Types of changes
<!--- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [ ] Improvement (non-breaking change that adds a new feature)
- [ ] Bug fix (fixes an issue)
- [ ] Breaking change (breaking change)
- [ ] Config and build (change in the configuration and build system,
has no impact on code or features)

## Checklist:
<!--- Go over all the following points, and put an `x` in all the boxes
that apply. -->
<!--- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
- [ ] My code follows the code style of this project.
- [ ] My change requires a change to the documentation.
- [ ] I have updated the documentation accordingly.
- [ ] I have added tests to cover my changes.
- [ ] All new and existing tests passed.

<!--- It would be nice if you could sign off your contribution by
replacing the name with your GitHub user name and GitHub email contact.
-->
Signed-off-by: GITHUB_USER <GITHUB_USER_EMAIL>
---
 src/boot/boot.h                      | 11 ++++++++++
 src/boot/boot_io.h                   |  9 +++++++++
 src/boot/crc32.h                     |  6 ++++++
 src/flashcart/flashcart.h            |  9 +++++++++
 src/flashcart/sc64/sc64.h            | 12 +++++++++++
 src/flashcart/sc64/sc64_internal.h   | 11 ++++++++++
 src/menu/actions.h                   |  6 ++++++
 src/menu/assets.h                    |  9 +++++++++
 src/menu/menu.h                      |  6 ++++++
 src/menu/menu_res_setup.h            |  6 ++++++
 src/menu/menu_state.h                | 10 ++++++++++
 src/menu/mp3player.h                 |  7 +++++++
 src/menu/path.h                      |  9 ++++++++-
 src/menu/rom_database.c              |  9 +++++++++
 src/menu/rom_database.h              | 30 ++++++++++++++++++++--------
 src/menu/settings.h                  |  7 +++++++
 src/menu/views/fragments/fragments.h | 14 +++++++++++++
 src/menu/views/views.h               | 11 ++++++++++
 18 files changed, 173 insertions(+), 9 deletions(-)

diff --git a/src/boot/boot.h b/src/boot/boot.h
index 4abd082a..fb4deafb 100644
--- a/src/boot/boot.h
+++ b/src/boot/boot.h
@@ -1,3 +1,9 @@
+/**
+ * @file boot.h
+ * @brief Flashcart Boot Subsystem
+ * @ingroup boot
+ */
+
 #ifndef BOOT_H__
 #define BOOT_H__
 
@@ -6,16 +12,20 @@
 #include <stdint.h>
 
 
+/** @brief Boot device type enumeration */
 typedef enum {
     BOOT_DEVICE_TYPE_ROM = 0,
     BOOT_DEVICE_TYPE_DD = 1,
 } boot_device_type_t;
 
+/** @brief Reset type enumeration */
 typedef enum {
     BOOT_RESET_TYPE_COLD = 0,
     BOOT_RESET_TYPE_NMI = 1,
 } boot_reset_type_t;
 
+
+/** @brief TV type enumeration */
 typedef enum {
     BOOT_TV_TYPE_PAL = 0,
     BOOT_TV_TYPE_NTSC = 1,
@@ -24,6 +34,7 @@ typedef enum {
 } boot_tv_type_t;
 
 
+/** @brief Boot Parameters Structure */
 typedef struct {
     boot_device_type_t device_type;
     boot_reset_type_t reset_type;
diff --git a/src/boot/boot_io.h b/src/boot/boot_io.h
index 0c07947d..1029d99c 100644
--- a/src/boot/boot_io.h
+++ b/src/boot/boot_io.h
@@ -1,3 +1,9 @@
+/**
+ * @file boot_io.h
+ * @brief Flashcart Boot IO
+ * @ingroup boot
+ */
+
 #ifndef BOOT_IO_H__
 #define BOOT_IO_H__
 
@@ -78,6 +84,7 @@ typedef struct {
 #define SP_SR_SET_SIG7              (1 << 24)
 
 
+/** @brief DPC Registers Structure */
 typedef struct {
     io32_t START;
     io32_t END;
@@ -115,6 +122,7 @@ typedef struct {
 #define DPC_SR_CLR_CLOCK_CTR        (1 << 9)
 
 
+/** @brief Video Interface Registers Structure */
 typedef struct {
     io32_t CR;
     io32_t MADDR;
@@ -167,6 +175,7 @@ typedef struct {
 #define AI_CR_DMA_ON                (1 << 0)
 
 
+/** @brief Parallel Interface Register Structure */
 typedef struct {
     io32_t MADDR;
     io32_t PADDR;
diff --git a/src/boot/crc32.h b/src/boot/crc32.h
index 0201ac58..85ad535d 100644
--- a/src/boot/crc32.h
+++ b/src/boot/crc32.h
@@ -1,3 +1,9 @@
+/**
+ * @file crc32.h
+ * @brief Flashcart Boot Checksum
+ * @ingroup boot
+ */
+
 #ifndef CRC32_H__
 #define CRC32_H__
 
diff --git a/src/flashcart/flashcart.h b/src/flashcart/flashcart.h
index 79a85489..cb92e089 100644
--- a/src/flashcart/flashcart.h
+++ b/src/flashcart/flashcart.h
@@ -1,3 +1,9 @@
+/**
+ * @file flashcart.h
+ * @brief Flashcart Subsystem
+ * @ingroup flashcart 
+ */
+
 #ifndef FLASHCART_H__
 #define FLASHCART_H__
 
@@ -6,6 +12,7 @@
 #include <stdint.h>
 
 
+/** @brief Flashcart error enumeration */
 typedef enum {
     FLASHCART_OK,
     FLASHCART_ERROR_NOT_DETECTED,
@@ -17,6 +24,7 @@ typedef enum {
     FLASHCART_ERROR_INT,
 } flashcart_error_t;
 
+/** @brief Flashcart save type enumeration */
 typedef enum {
     FLASHCART_SAVE_TYPE_NONE,
     FLASHCART_SAVE_TYPE_EEPROM_4K,
@@ -28,6 +36,7 @@ typedef enum {
     __FLASHCART_SAVE_TYPE_END
 } flashcart_save_type_t;
 
+/** @brief Flashcart Structure */
 typedef struct {
     flashcart_error_t (*init) (void);
     flashcart_error_t (*deinit) (void);
diff --git a/src/flashcart/sc64/sc64.h b/src/flashcart/sc64/sc64.h
index fff87bb2..fc0c6f4d 100644
--- a/src/flashcart/sc64/sc64.h
+++ b/src/flashcart/sc64/sc64.h
@@ -1,11 +1,23 @@
+/**
+ * @file flashcart.h
+ * @brief SC64 Flashcart Utilities
+ * @ingroup flashcart 
+ */
+
 #ifndef FLASHCART_SC64_H__
 #define FLASHCART_SC64_H__
 
 
 #include "../flashcart.h"
 
+/**
+ * @addtogroup sc64
+ * @{
+ */
+
 
 flashcart_t *sc64_get_flashcart (void);
 
+/** @} */ /* sc64 */
 
 #endif
diff --git a/src/flashcart/sc64/sc64_internal.h b/src/flashcart/sc64/sc64_internal.h
index 182bbe37..eb09eeb8 100644
--- a/src/flashcart/sc64/sc64_internal.h
+++ b/src/flashcart/sc64/sc64_internal.h
@@ -1,3 +1,9 @@
+/**
+ * @file flashcart.h
+ * @brief SC64 Flashcart Internal Utilities
+ * @ingroup flashcart 
+ */
+
 #ifndef FLASHCART_SC64_INTERNAL_H__
 #define FLASHCART_SC64_INTERNAL_H__
 
@@ -5,6 +11,10 @@
 #include <stddef.h>
 #include <stdint.h>
 
+/**
+ * @addtogroup sc64
+ * @{
+ */
 
 typedef struct {
     uint8_t BUFFER[8192];
@@ -72,5 +82,6 @@ sc64_error_t sc64_flash_wait_busy (void);
 sc64_error_t sc64_flash_get_erase_block_size (size_t *erase_block_size);
 sc64_error_t sc64_flash_erase_block (void *address);
 
+/** @} */ /* sc64 */
 
 #endif
diff --git a/src/menu/actions.h b/src/menu/actions.h
index 1695e93f..f890b55c 100644
--- a/src/menu/actions.h
+++ b/src/menu/actions.h
@@ -1,3 +1,9 @@
+/**
+ * @file actions.h
+ * @brief Menu Actions
+ * @ingroup menu 
+ */
+
 #ifndef ACTIONS_H__
 #define ACTIONS_H__
 
diff --git a/src/menu/assets.h b/src/menu/assets.h
index 67ea8ad2..a4d6dea1 100644
--- a/src/menu/assets.h
+++ b/src/menu/assets.h
@@ -1,3 +1,9 @@
+/**
+ * @file assets.h
+ * @brief Menu Assets
+ * @ingroup menu 
+ */
+
 #ifndef ASSETS_H__
 #define ASSETS_H__
 
@@ -5,8 +11,11 @@
 #include <rdpq_font.h>
 
 
+/** @brief Assets Structure */
 typedef struct {
+    /** @brief RDPQ Font */
     rdpq_font_t *font;
+    /** @brief Font Height */
     int font_height;
 } assets_t;
 
diff --git a/src/menu/menu.h b/src/menu/menu.h
index 7d538203..a5cd14d4 100644
--- a/src/menu/menu.h
+++ b/src/menu/menu.h
@@ -1,3 +1,9 @@
+/**
+ * @file menu.h
+ * @brief Menu Subsystem
+ * @ingroup menu 
+ */
+
 #ifndef MENU_H__
 #define MENU_H__
 
diff --git a/src/menu/menu_res_setup.h b/src/menu/menu_res_setup.h
index 76cd684c..48ccea39 100644
--- a/src/menu/menu_res_setup.h
+++ b/src/menu/menu_res_setup.h
@@ -1,3 +1,9 @@
+/**
+ * @file menu_res_setup.h
+ * @brief Menu Resolution (non RDPQ)
+ * @ingroup menu 
+ */
+
 #ifndef MENU_RES_SETUP_H__
 #define MENU_RES_SETUP_H__
 
diff --git a/src/menu/menu_state.h b/src/menu/menu_state.h
index c201367b..677ecab5 100644
--- a/src/menu/menu_state.h
+++ b/src/menu/menu_state.h
@@ -1,3 +1,9 @@
+/**
+ * @file menu_state.h
+ * @brief Menu State
+ * @ingroup menu 
+ */
+
 #ifndef MENU_STRUCT_H__
 #define MENU_STRUCT_H__
 
@@ -11,6 +17,7 @@
 #define BROWSER_LIST_SIZE   10000
 
 
+/** @brief Menu mode enumeration */
 typedef enum {
     MENU_MODE_NONE,
     MENU_MODE_STARTUP,
@@ -25,6 +32,7 @@ typedef enum {
     MENU_MODE_BOOT,
 } menu_mode_t;
 
+/** @brief File entry type enumeration */
 typedef enum {
     ENTRY_TYPE_DIR,
     ENTRY_TYPE_ROM,
@@ -33,12 +41,14 @@ typedef enum {
     ENTRY_TYPE_OTHER,
 } entry_type_t;
 
+/** @brief File Entry Structure */
 typedef struct {
     char *name;
     entry_type_t type;
     int size;
 } entry_t;
 
+/** @brief Menu Structure */
 typedef struct {
     menu_mode_t mode;
     menu_mode_t next_mode;
diff --git a/src/menu/mp3player.h b/src/menu/mp3player.h
index 85d078ed..add0dbfd 100644
--- a/src/menu/mp3player.h
+++ b/src/menu/mp3player.h
@@ -1,3 +1,9 @@
+/**
+ * @file mp3player.h
+ * @brief MP3 Player
+ * @ingroup menu 
+ */
+
 #ifndef MP3PLAYER_H__
 #define MP3PLAYER_H__
 
@@ -5,6 +11,7 @@
 #include <stdbool.h>
 
 
+/** @brief MP3 file error enumeration */
 typedef enum {
     MP3PLAYER_OK,
     MP3PLAYER_ERR_MALLOC,
diff --git a/src/menu/path.h b/src/menu/path.h
index 3f947b19..e53dc363 100644
--- a/src/menu/path.h
+++ b/src/menu/path.h
@@ -1,10 +1,17 @@
-#ifndef PAHT_H__
+/**
+ * @file path.h
+ * @brief Menu Path
+ * @ingroup menu 
+ */
+
+#ifndef PATH_H__
 #define PATH_H__
 
 
 #include <stdbool.h>
 
 
+/** @brief Path Structure */
 typedef struct {
     char *buffer;
     size_t capacity;
diff --git a/src/menu/rom_database.c b/src/menu/rom_database.c
index 76ddddce..642ffcba 100644
--- a/src/menu/rom_database.c
+++ b/src/menu/rom_database.c
@@ -43,6 +43,15 @@ rom_header_t file_read_rom_header(char *path) {
 
     rom_header_t *rom_header = malloc(sizeof(rom_header_t));
 
+    //Rom File Info
+    // CheckCode 0x10, 8 bytes (sometimes refered to as CRC Hi and CRC Lo)
+    // GameTitle 0x20, 20 bytes
+    // GameCode ->
+    //    CategoryCode 0x3b
+    //    UniqueCode 0x3c and 0x3d
+    //    DestinationCode 0x3e
+    // RomVersion 0x3f
+
     fseek(fp, 0x00, SEEK_SET);
     fread(&(rom_header->endian), sizeof(uint32_t), 1, fp);
     // FIXME: handle endian appropriately, perhaps: cart_card_byteswap
diff --git a/src/menu/rom_database.h b/src/menu/rom_database.h
index 79f7ed2b..d7c10e82 100644
--- a/src/menu/rom_database.h
+++ b/src/menu/rom_database.h
@@ -1,8 +1,15 @@
+/**
+ * @file rom_database.h
+ * @brief ROM Database
+ * @ingroup menu 
+ */
+
 #ifndef ROM_DATABASE_H__
 #define ROM_DATABASE_H__
 
 #include <stdint.h>
 
+
 // NOTE: these values are independent of flashcart / OS
 // But by default align to SC64.
 #define DB_SAVE_TYPE_NONE           0x00
@@ -16,15 +23,20 @@
 #define DB_SAVE_TYPE_DD             0x20
 #define DB_SAVE_TYPE_INVALID        0xff
 
+/** @brief ROM System Memory requirements enumeration */
 typedef enum {
+    /** @brief The ROM is happy with 4K of memory */
     DB_MEMORY_EXPANSION_NONE =      0x00,
+    /** @brief The ROM requires 8K of memory */
     DB_MEMORY_EXPANSION_REQUIRED =  0x01,
     DB_MEMORY_EXPANSION_SUGGESTED = 0x02,
     DB_MEMORY_EXPANSION_ENHANCED =  0x03,
+    /** @brief The ROM is faulty when using 8K of memory */
     DB_MEMORY_EXPANSION_FAULTY =    0x04,
 } rom_memorytype_t;
 
 
+/** @brief N64 ROM Homebrew save type enumeration */
 typedef enum {
     HB_SAVE_TYPE_NONE =         0x00,
     HB_SAVE_TYPE_EEPROM_4K =    0x01,
@@ -35,6 +47,7 @@ typedef enum {
     HB_SAVE_TYPE_SRAM_128K =    0x06,
 } homebrew_savetype_t;
 
+/** @brief N64 ROM endian enumeration */
 typedef enum {
     ROM_BIG_ENDIAN =        0x80371240,
     ROM_LITTLE_ENDIAN =     0x40123780,
@@ -43,15 +56,8 @@ typedef enum {
     IPL_BIG_ENDIAN =        0x80270740,
 } rom_endian_type_t;
 
-//Rom Info
-// CheckCode 0x10, 8 bytes (sometimes refered to as CRC Hi and CRC Lo)
-// GameTitle 0x20, 20 bytes
-// GameCode ->
-//    CategoryCode 0x3b
-//    UniqueCode 0x3c and 0x3d
-//    DestinationCode 0x3e
-// RomVersion 0x3f
 
+/** @brief N64 ROM media type enumeration */
 typedef enum {
     N64_CART = 'N',
     N64_DISK  = 'D',
@@ -60,6 +66,7 @@ typedef enum {
     N64_ALECK64  = 'Z'
 } rom_media_type_t;
 
+/** @brief N64 ROM market type enumeration */
 typedef enum {
     MARKET_ALL = 'A',
     MARKET_BRAZIL  = 'B',
@@ -90,17 +97,24 @@ typedef enum {
 } rom_destination_market_t;
 
 
+/** @brief N64 ROM Metadata Structure */
 typedef struct {
     uint8_t media_type; // rom_media_type_t
     uint16_t unique_identifier;
     uint8_t destination_market; // rom_destination_market_t
 } rom_metadata_t;
 
+/** @brief N64 ROM Header Structure */
 typedef struct {
+    /** @brief The N64 ROM file endian */
     uint32_t endian; // rom_endian_type_t
+    /** @brief The N64 ROM file checksum */
     uint64_t checksum;
+    /** @brief The N64 ROM file title */
     char title[21]; // 20 chars + null
+    /** @brief The N64 ROM file metadata */
     rom_metadata_t metadata;
+    /** @brief The N64 ROM file version */
     uint8_t version;
 } rom_header_t;
 
diff --git a/src/menu/settings.h b/src/menu/settings.h
index 049f982e..90833dba 100644
--- a/src/menu/settings.h
+++ b/src/menu/settings.h
@@ -1,7 +1,14 @@
+/**
+ * @file settings.h
+ * @brief Menu Settings
+ * @ingroup menu 
+ */
+
 #ifndef SETTINGS_H__
 #define SETTINGS_H__
 
 
+/** @brief Settings Structure */
 typedef struct {
     bool pal60;
     bool show_hidden_files;
diff --git a/src/menu/views/fragments/fragments.h b/src/menu/views/fragments/fragments.h
index 1fe444dc..9c4170c6 100644
--- a/src/menu/views/fragments/fragments.h
+++ b/src/menu/views/fragments/fragments.h
@@ -1,9 +1,20 @@
+/**
+ * @file fragments.h
+ * @brief Menu View Fragments
+ * @ingroup menu 
+ */
+
 #ifndef FRAGMENTS_H__
 #define FRAGMENTS_H__
 
 
 #include <surface.h>
 
+/**
+ * @addtogroup view_fragments
+ * @{
+ */
+
 
 void widget_horizontal_line (int x1, int x2, int y, int thickness);
 void widget_border (int x1, int y1, int x2, int y2, int thickness);
@@ -11,6 +22,7 @@ void widget_scrollbar (int x, int y, int width, int height, int position, int it
 void widget_progressbar (int x, int y, int width, int height, float progress);
 
 
+/** @brief Layout Structure */
 typedef struct {
     int offset_x;
     int offset_y;
@@ -41,4 +53,6 @@ void fragment_text_set_color (color_t color);
 int fragment_textf (int x, int y, char *fmt, ...);
 
 
+/** @} */ /* view_fragments */
+
 #endif
diff --git a/src/menu/views/views.h b/src/menu/views/views.h
index 84e01317..ccf3ecba 100644
--- a/src/menu/views/views.h
+++ b/src/menu/views/views.h
@@ -1,3 +1,9 @@
+/**
+ * @file views.h
+ * @brief Menu Views
+ * @ingroup menu 
+ */
+
 #ifndef VIEWS_H__
 #define VIEWS_H__
 
@@ -6,6 +12,10 @@
 
 #include "../menu_state.h"
 
+/**
+ * @addtogroup view
+ * @{
+ */
 
 void view_startup_init (menu_t *menu);
 void view_startup_display (menu_t *menu, surface_t *display);
@@ -34,5 +44,6 @@ void view_error_display (menu_t *menu, surface_t *display);
 void view_fault_init (menu_t *menu);
 void view_fault_display (menu_t *menu, surface_t *display);
 
+/** @} */ /* view */
 
 #endif