Fully integrate Doxygen.

.github/workflows/build-atmega1284p-debug.yaml

@@ -14,21 +14,21 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    
+
     - name: Install
       # Install AVR GCC toolchain
       run : |
         sudo apt-get update
-        sudo apt-get install -y gcc-avr binutils-avr avr-libc cmake make
-        
+        sudo apt-get install -y avr-libc binutils-avr cmake doxygen gcc-avr graphviz make
+
     - name: Check Out
       # Check out latest code
       uses: actions/checkout@v4
-      
+
     - name: Configure
       # Configure build environment in build/ directory
       run: cmake -B ${{github.workspace}}/build -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}
-      
+
     - name: Build
       # Execute the build
       run: cmake --build ${{github.workspace}}/build --config ${{env.BUILD_TYPE}}
@@ -39,7 +39,7 @@ jobs:
       with:
         name: superkey.elf
         path: build/superkey.elf
-        
+
     - name: Upload Artifact (superkey.elf.stripped)
       # Upload stripped ELF file
       uses: actions/upload-artifact@v4
@@ -53,18 +53,18 @@ jobs:
       with:
         name: superkey.ihex
         path: build/superkey.ihex
-        
+
     - name: Upload Artifact (superkey.map)
       # Upload memory map file
       uses: actions/upload-artifact@v4
       with:
         name: superkey.map
         path: build/superkey.map
-        
+
     - name: Upload Artifact (superkey.txt)
       # Upload executable text dump
       uses: actions/upload-artifact@v4
       with:
         name: superkey.txt
         path: build/superkey.txt
-        
+

.github/workflows/build-atmega1284p-release.yaml

@@ -14,21 +14,21 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    
+
     - name: Install
       # Install AVR GCC toolchain
       run : |
         sudo apt-get update
-        sudo apt-get install -y gcc-avr binutils-avr avr-libc cmake make
-        
+        sudo apt-get install -y avr-libc binutils-avr cmake doxygen gcc-avr graphviz make
+
     - name: Check Out
       # Check out latest code
       uses: actions/checkout@v4
-      
+
     - name: Configure
       # Configure build environment in build/ directory
       run: cmake -B ${{github.workspace}}/build -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}
-      
+
     - name: Build
       # Execute the build
       run: cmake --build ${{github.workspace}}/build --config ${{env.BUILD_TYPE}}
@@ -39,7 +39,7 @@ jobs:
       with:
         name: superkey.elf
         path: build/superkey.elf
-        
+
     - name: Upload Artifact (superkey.elf.stripped)
       # Upload stripped ELF file
       uses: actions/upload-artifact@v4
@@ -53,18 +53,18 @@ jobs:
       with:
         name: superkey.ihex
         path: build/superkey.ihex
-        
+
     - name: Upload Artifact (superkey.map)
       # Upload memory map file
       uses: actions/upload-artifact@v4
       with:
         name: superkey.map
         path: build/superkey.map
-        
+
     - name: Upload Artifact (superkey.txt)
       # Upload executable text dump
       uses: actions/upload-artifact@v4
       with:
         name: superkey.txt
         path: build/superkey.txt
-        
+

.vscode/c_cpp_properties.json

@@ -4,7 +4,6 @@
             "name": "AVR (ATMega1284P)",
             "includePath": [
                 "${workspaceFolder}/build/autogen/superkey",
-                "${workspaceFolder}/lib",
                 "${workspaceFolder}/src/main"
             ],
             "defines": [

CMakeLists.txt

@@ -10,6 +10,7 @@ cmake_minimum_required(VERSION 3.22)
 
 # -- Packages --
 
+find_package(Doxygen REQUIRED)
 find_package(Git REQUIRED)
 
 # -- Project Configuration --
@@ -104,6 +105,34 @@ add_link_options(
     -mmcu=${DEVICE_MCU}
 )
 
+# -- Documentation Setup --
+
+# CMake will automatically generate the Doxyfile in the build directory based on the Doxyfile.in template
+set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
+set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+# Set Doxygen options
+set(DOXYGEN_EXTRACT_ALL NO)
+set(DOXYGEN_WARN_IF_UNDOCUMENTED YES)
+if(CMAKE_BUILD_TYPE STREQUAL "Debug")
+    set(DOXYGEN_EXTRACT_ALL YES)
+    set(DOXYGEN_WARN_IF_UNDOCUMENTED NO)
+endif()
+
+# Configure the Doxyfile
+configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
+
+# Add custom target for Doxygen
+# (Running `make doxygen` will build the documents in the build directory)
+add_custom_target(
+    doxygen
+    ALL
+    COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    COMMENT "Generating documentation with Doxygen"
+    VERBATIM
+)
+
 # -- Subdirectories --
 
 # Main executable

Doxyfile.in

@@ -0,0 +1,24 @@
+#
+# @file     Doxyfile
+# @brief    Doxyfile for generating Doxygen documentation.
+#
+# @author   Chris Vig (chris@invictus.so)
+# @date     2025-08-25
+#
+# NOTE:
+# CMake processes Doxyfile.in in the root directory, and saves it to build/Doxyfile, which is then used to generate the
+# documentation with Doxygen by running `make doxygen`.
+#
+
+PROJECT_NAME            = @PROJECT_NAME@
+OUTPUT_DIRECTORY        = @CMAKE_CURRENT_BINARY_DIR@/docs
+INPUT                   = @CMAKE_SOURCE_DIR@/readme.md \
+                          @CMAKE_SOURCE_DIR@/src
+RECURSIVE               = YES
+EXTRACT_ALL             = @DOXYGEN_EXTRACT_ALL@
+WARN_IF_UNDOCUMENTED    = @DOXYGEN_WARN_IF_UNDOCUMENTED@
+GENERATE_LATEX          = NO
+GENERATE_HTML           = YES
+EXCLUDE_SYMBOLS         = _Static_assert ISR
+USE_MDFILE_AS_MAINPAGE  = @CMAKE_SOURCE_DIR@/readme.md
+MARKDOWN_SUPPORT        = YES

configuration.cmake

@@ -49,7 +49,6 @@ set(CONFIG_DFLT_KEYER_OUTPUT_ACTIVE_LOW     true
 set(CONFIG_DFLT_KEYER_INVERT_PADDLES        false
     CACHE STRING                            "Set to true to invert the paddles. (true / false)")
 
-
 # Set defines
 add_compile_definitions(
     _CONFIG_DFLT_WPM=${CONFIG_DFLT_WPM}

readme.md

@@ -1,17 +1,19 @@
-# `SUPERKEY`
+# SuperKey
 
 **SuperKey** - the greatest CW keyer the world has ever seen.
 
 This will be a README someday.
 
 ## Build Status
 
-[![Build - AVR ATmega1284P (Debug)](https://github.com/xchrishawk/superkey/actions/workflows/build-atmega1284p-debug.yaml/badge.svg)](https://github.com/xchrishawk/superkey/actions/workflows/build-atmega1284p-debug.yaml)  
+[![Build - AVR ATmega1284P (Debug)](https://github.com/xchrishawk/superkey/actions/workflows/build-atmega1284p-debug.yaml/badge.svg)](https://github.com/xchrishawk/superkey/actions/workflows/build-atmega1284p-debug.yaml)<br/>
 [![Build - AVR ATmega1284P (Release)](https://github.com/xchrishawk/superkey/actions/workflows/build-atmega1284p-release.yaml/badge.svg)](https://github.com/xchrishawk/superkey/actions/workflows/build-atmega1284p-release.yaml)
 
 ## Notes
 
-### `avrdude` Upload Command
+### Upload Command
+
+The executable is uploaded to the MCU using [`avrdude`](https://www.nongnu.org/avrdude/) and an [AVRISP mkII programmer](https://a.co/d/59zSwb5).
 
 ```
 avrdude -c avrispmkii -P usb -p m1284p -U flash:w:superkey.ihex -D

src/main/application/config.c

@@ -1,5 +1,5 @@
 /**
- * @file    src/main/core/config.c
+ * @file    src/main/application/config.c
  * @brief   Implementation for the application configuration module.
  *
  * @author  Chris Vig (chris@invictus.so)

src/main/application/config.h

@@ -23,7 +23,7 @@
 /* ----------------------------------------------------- TYPES ------------------------------------------------------ */
 
 /**
- * @typedef config_t
+ * @struct  config_t
  * @brief   Struct containing the current application configuration information.
  */
 typedef struct

src/main/application/debug_port.c

@@ -63,7 +63,7 @@
 #define DISABLED_STR            "disabled"
 
 /**
- * @define  OFF_STR
+ * @def     OFF_STR
  * @brief   The token which indicates that an input or output is off.
  */
 #define OFF_STR                 "off"

src/main/application/input.c

@@ -35,11 +35,24 @@ _Static_assert( array_count( s_pin_tbl ) == INPUT_PIN_COUNT, "Invalid pin table!
 
 /* ----------------------------------------------------- MACROS ----------------------------------------------------- */
 
-// Validation macros
+/**
+ * @def     validate_pin( _pin )
+ * @brief   Validates that the specified `input_pin_t` is valid.
+ */
 #define validate_pin( _pin )                                                            \
     assert_always( ( _pin ) < INPUT_PIN_COUNT )
+
+/**
+ * @def     validate_polarity( _polarity )
+ * @brief   Validates that the specified `input_polarity_t` is valid.
+ */
 #define validate_polarity( _polarity )                                                  \
     assert_always( ( _polarity ) < INPUT_POLARITY_COUNT )
+
+/**
+ * @def     validate_type( _type )
+ * @brief   Validates that the specified `input_type_t` is valid.
+ */
 #define validate_type( _input )                                                         \
     assert_always( ( _input ) < INPUT_TYPE_COUNT )
 

src/main/application/input.h

@@ -54,7 +54,7 @@ enum
 };
 
 /**
- * @typedef input_type_tt
+ * @typedef input_type_t
  * @brief   Enumeration of the supported input types.
  */
 typedef uint8_t input_type_t;

src/main/application/keyer.c

@@ -89,11 +89,24 @@ static tick_t s_space_ticks = 0;            /**< Number of ticks per element spa
 
 /* ----------------------------------------------------- MACROS ----------------------------------------------------- */
 
-// Utility macros
+/**
+ * @def     is_timeout_elapsed( _tick, _duration )
+ * @brief   Returns `true` if the specified timeout has elapsed at the specified tick.
+ */
 #define is_timeout_elapsed( _tick, _duration )                                      \
     ( sys_elapsed( ( _tick ), s_element_start ) > ( _duration ) )
+
+/**
+ * @def     is_duration_elapsed( _tick )
+ * @brief   Returns `true` if the `s_element_duration` timeout has elapsed at the specified tick.
+ */
 #define is_duration_elapsed( _tick )                                                \
     is_timeout_elapsed( _tick, s_element_duration )
+
+/**
+ * @def     is_lockout_elapsed( _tick )
+ * @brief   Returns `true` if the `s_element_lockout` timeout has elapsed at the specified tick.
+ */
 #define is_lockout_elapsed( _tick )                                                 \
     is_timeout_elapsed( _tick, s_element_lockout )
 
@@ -136,7 +149,7 @@ static void do_state_on( tick_t tick, bool new_state );
 static bool get_keyed( void );
 
 /**
- * @fn      next_state( void )
+ * @fn      get_next_state( void )
  * @brief   Returns the next keyer state, based on current inputs.
  */
 static state_t get_next_state( void );

src/main/application/keyer.h

@@ -64,7 +64,7 @@ bool keyer_get_invert_paddles( void );
 keyer_mode_t keyer_get_mode( void );
 
 /**
- * @fn      keyer_get_active_low( void )
+ * @fn      keyer_get_output_active_low( void )
  * @brief   Returns `true` if the keyer's output is active low.
  */
 bool keyer_get_output_active_low( void );

src/main/application/wpm.c

@@ -50,6 +50,7 @@ void wpm_set( wpm_t wpm )
 
 }   /* wpm_set() */
 
+
 void wpm_ticks( wpm_t wpm,
                 tick_t * dot,
                 tick_t * dash,

src/main/application/wpm.h

@@ -61,7 +61,7 @@ wpm_t wpm_get( void );
 void wpm_set( wpm_t wpm );
 
 /**
- * @fn      wpm_ticks( wpm, tick_t *, tick_t *, tick_t *, tick_t *, tick_t * )
+ * @fn      wpm_ticks( wpm_t, tick_t *, tick_t *, tick_t *, tick_t *, tick_t * )
  * @brief   Calculates the duration (in ticks) of various Morse code elements.
  * @note    This function does floating-point math and should not be called frequently.
  */

src/main/core/main.c

@@ -30,13 +30,32 @@
 
 /* --------------------------------------------------- CONSTANTS ---------------------------------------------------- */
 
-// Periodic processing periods in ticks
+/**
+ * @def     TICKS_1_MS
+ * @brief   Number of ticks for 1 millisecond tasks.
+ */
 #define TICKS_1_MS      ( 1 * TICKS_PER_MSEC )
+
+/**
+ * @def     TICKS_50_MS
+ * @brief   Number of ticks for 50 millisecond tasks.
+ */
 #define TICKS_50_MS     ( 50 * TICKS_PER_MSEC )
+
+/**
+ * @def     TICKS_1_S
+ * @brief   Number of ticks for 1 second tasks.
+ */
 #define TICKS_1_S       ( 1 * TICKS_PER_SEC )
 
 /* ---------------------------------------------- PROCEDURE PROTOTYPES ---------------------------------------------- */
 
+/**
+ * @fn      main( void )
+ * @brief   Main entry point for the application.
+ */
+int main( void );
+
 /**
  * @fn      handle_input_state( void )
  * @brief   Handles the `EVENT_INPUT_STATE` event.
@@ -71,7 +90,7 @@ static void init( void );
  * @fn      main_loop( void )
  * @brief   Runs the main loop of the application.
  */
-static void main_loop( void ) FUNC_NEVER_RETURNS;
+static void main_loop( void );
 
 /**
  * @fn      periodic_1ms( tick_t )