Further header documentation improvements

src/menu/fonts.h

@@ -7,23 +7,39 @@
 #ifndef FONTS_H__
 #define FONTS_H__
 
-/** @brief Font type enumeration. */
+/**
+ * @brief Font type enumeration.
+ * 
+ * This enumeration defines the different types of fonts that can be used
+ * in the menu system.
+ */
 typedef enum {
-    FNT_DEFAULT = 1,
+    FNT_DEFAULT = 1, /**< Default font type */
 } menu_font_type_t;
 
-/** @brief Font style enumeration. */
+/**
+ * @brief Font style enumeration.
+ * 
+ * This enumeration defines the different styles of fonts that can be used
+ * in the menu system.
+ */
 typedef enum {
-    STL_DEFAULT = 0,
+    STL_DEFAULT = 0, /**< Default font style */
-    STL_GREEN,
+    STL_GREEN,       /**< Green font style */
-    STL_BLUE,
+    STL_BLUE,        /**< Blue font style */
-    STL_YELLOW,
+    STL_YELLOW,      /**< Yellow font style */
-    STL_ORANGE,
+    STL_ORANGE,      /**< Orange font style */
-    STL_GRAY,
+    STL_GRAY,        /**< Gray font style */
 } menu_font_style_t;
 
+/**
+ * @brief Initialize fonts.
+ * 
+ * This function initializes the fonts used in the menu system. It can load
+ * custom fonts from the specified path.
+ * 
+ * @param custom_font_path Path to the custom font file.
+ */
+void fonts_init(char *custom_font_path);
 
-void fonts_init (char *custom_font_path);
+#endif /* FONTS_H__ */
-
-
-#endif

src/menu/png_decoder.h

@@ -7,27 +7,68 @@
 #ifndef PNG_DECODER_H__
 #define PNG_DECODER_H__
 
-
 #include <surface.h>
 
-
+/** 
-/** @brief PNG decoder errors */
+ * @brief PNG decoder errors 
+ * 
+ * Enumeration for different types of errors that can occur in the PNG decoder.
+ */
 typedef enum {
-    PNG_OK,
+    PNG_OK,               /**< No error */
-    PNG_ERR_INT,
+    PNG_ERR_INT,          /**< Internal error */
-    PNG_ERR_BUSY,
+    PNG_ERR_BUSY,         /**< Decoder is busy */
-    PNG_ERR_OUT_OF_MEM,
+    PNG_ERR_OUT_OF_MEM,   /**< Out of memory error */
-    PNG_ERR_NO_FILE,
+    PNG_ERR_NO_FILE,      /**< No file found error */
-    PNG_ERR_BAD_FILE,
+    PNG_ERR_BAD_FILE,     /**< Bad file error */
 } png_err_t;
 
+/**
+ * @brief PNG decoder callback type.
+ * 
+ * This typedef defines the callback function type used by the PNG decoder.
+ * 
+ * @param err Error code indicating the result of the decoding process.
+ * @param decoded_image Pointer to the decoded image surface.
+ * @param callback_data User-defined data passed to the callback function.
+ */
 typedef void png_callback_t (png_err_t err, surface_t *decoded_image, void *callback_data);
 
-
+/**
+ * @brief Start the PNG decoding process.
+ * 
+ * This function starts the PNG decoding process for the specified file.
+ * 
+ * @param path Path to the PNG file.
+ * @param max_width Maximum width of the decoded image.
+ * @param max_height Maximum height of the decoded image.
+ * @param callback Callback function to be called when decoding is complete.
+ * @param callback_data User-defined data to be passed to the callback function.
+ * @return png_err_t Error code indicating the result of the start operation.
+ */
 png_err_t png_decoder_start (char *path, int max_width, int max_height, png_callback_t *callback, void *callback_data);
+
+/**
+ * @brief Abort the PNG decoding process.
+ * 
+ * This function aborts the ongoing PNG decoding process.
+ */
 void png_decoder_abort (void);
+
+/**
+ * @brief Get the progress of the PNG decoding process.
+ * 
+ * This function returns the current progress of the PNG decoding process as a percentage.
+ * 
+ * @return float Current progress of the decoding process (0.0 to 100.0).
+ */
 float png_decoder_get_progress (void);
+
+/**
+ * @brief Poll the PNG decoder.
+ * 
+ * This function polls the PNG decoder to handle any ongoing decoding tasks.
+ */
 void png_decoder_poll (void);
 
-
+#endif /* PNG_DECODER_H__ */
-#endif

src/menu/sound.h

@@ -9,28 +9,46 @@
 
 #include <stdbool.h>
 
-#define SOUND_MP3_PLAYER_CHANNEL    (0)
+#define SOUND_MP3_PLAYER_CHANNEL    (0) /**< Channel for MP3 player sound */
-#define SOUND_SFX_CHANNEL           (2)
+#define SOUND_SFX_CHANNEL           (2) /**< Channel for sound effects */
 
 /**
  * @brief Enumeration of available sound effects for menu interactions.
+ * 
+ * This enumeration defines the different sound effects that can be used
+ * for menu interactions.
  */
 typedef enum {
-    SFX_CURSOR,
+    SFX_CURSOR,  /**< Sound effect for cursor movement */
-    SFX_ERROR,
+    SFX_ERROR,   /**< Sound effect for error */
-    SFX_ENTER,
+    SFX_ENTER,   /**< Sound effect for entering a menu */
-    SFX_EXIT,
+    SFX_EXIT,    /**< Sound effect for exiting a menu */
-    SFX_SETTING,
+    SFX_SETTING, /**< Sound effect for changing a setting */
 } sound_effect_t;
 
-
+/**
-void sound_init_default (void);
+ * @brief Initialize the default sound system.
-void sound_init_mp3_playback (void);
+ * 
+ * This function initializes the default sound system, setting up
+ * necessary resources and configurations.
+ */
+void sound_init_default(void);
 
 /**
- * @brief Initialize sound effects system.
+ * @brief Initialize the MP3 playback system.
+ * 
+ * This function initializes the MP3 playback system, preparing it
+ * for playing MP3 files.
  */
-void sound_init_sfx (void);
+void sound_init_mp3_playback(void);
+
+/**
+ * @brief Initialize the sound effects system.
+ * 
+ * This function initializes the sound effects system, setting up
+ * necessary resources and configurations for playing sound effects.
+ */
+void sound_init_sfx(void);
 
 /**
  * @brief Enable or disable sound effects.
@@ -46,4 +64,4 @@ void sound_play_effect(sound_effect_t sfx);
 void sound_deinit (void);
 void sound_poll (void);
 
-#endif
+#endif /* SOUND_H__ */

src/menu/usb_comm.h

@@ -2,20 +2,36 @@
  * @file usb_comm.h
  * @brief USB communication subsystem
  * @ingroup menu
+ *
+ * This file contains the declarations for the USB communication subsystem
+ * used in the menu system.
  */
 
 #ifndef USB_COMM_H__
 #define USB_COMM_H__
 
-
 #include "menu_state.h"
 
-
 #ifndef NDEBUG
-void usb_comm_poll (menu_t *menu);
+/**
+ * @brief Poll the USB communication subsystem.
+ *
+ * This function polls the USB communication subsystem to handle any
+ * incoming or outgoing data. It is only available in debug builds.
+ *
+ * @param menu Pointer to the menu structure.
+ */
+void usb_comm_poll(menu_t *menu);
 #else
+/**
+ * @brief Poll the USB communication subsystem (no-op in release builds).
+ *
+ * This macro is a no-op in release builds, where USB communication polling
+ * is disabled.
+ *
+ * @param menu Pointer to the menu structure.
+ */
 #define usb_comm_poll(menu)
 #endif
 
-
+#endif /* USB_COMM_H__ */
-#endif