Doxygen: Last fix for doxygen warnings in a series.

Used Copilot w/ Claude.

Author: emrainey

modules/core/include/core/Ring.hpp

@@ -149,8 +149,8 @@ class Ring final {
         return false;
     }
 
-    /// @brief Peeks at the first element in the Ring without removing it
-    /// @param output The reference to the first element. When the Ring is empty, the value of the element is undefined.
+    /// @brief Peeks at the first element in the Ring without removing it.
+    /// @return The reference to the first element in the Ring. When the Ring is empty, behavior is undefined.
     ValueType& Peek() { return buffer_[head_]; }
 
     /// @brief The indexing operator for mutable access

modules/core/include/core/StateChart.hpp

@@ -77,8 +77,6 @@ class StateChart {
 
     /// @brief The parameter constructor
     /// @param callback The reference to the callback interface
-    /// @param initial_state The initial state of the StateChart
-    /// @param final_state The final state of the StateChart
     StateChart(Callback& callback)
         : callback_{callback}
         , state_{StateType::Undefined} {}

modules/core/include/core/StateMachine.hpp

@@ -58,7 +58,6 @@ class StateMachine {
     /// @brief The parameter constructor
     /// @param callback The reference to the callback interface
     /// @param initial_state The initial state of the StateMachine
-    /// @param final_state The final state of the StateMachine
     StateMachine(Callback& callback, StateType initial_state)
         : callback_{callback}
         , initial_state_{initial_state}

modules/core/include/core/Units.hpp

@@ -38,12 +38,6 @@
 namespace core {
 /// @brief The namespace for the core units of measure and their constants
 namespace units {
-
-/// User-defined literal for creating Celsius temperature values
-constexpr Celsius operator""_c(long double value) {
-    return Celsius{static_cast<double>(value)};
-}
-
 /// @brief The unit of Length is Meters
 using Length = Meters;
 /// @brief The unit of Area is Square Meters
@@ -302,6 +296,9 @@ namespace physics {
 constexpr static Speed c = 299'792'458.0_mps;
 }    // namespace physics
 
+/// User-defined literal for speed as a multiple of the speed of light
+/// @param value The multiple of c (e.g., 0.5_c = 149,896,229 m/s)
+/// @return Speed value in meters per second
 constexpr Speed operator""_c(long double value) {
     return Speed{physics::c.value() * static_cast<Speed::Type>(value)};
 }

modules/cortex/include/cortex/peripherals/InstructionTraceMacrocell.hpp

@@ -287,8 +287,7 @@ struct DataWatchAndTrace final {
     /// The Cluster Register
 };
 
-/// The Trace Point Interface Unit
-/// @aka TPIU
+/// The Trace Port Interface Unit (TPIU)
 struct TracePortInterfaceUnit final {
     /// @brief The bitfield definition of the register
     struct SupportedParallelPortSizes final {

modules/cortex/include/cortex/peripherals/SystemControlBlock.hpp

@@ -223,8 +223,10 @@ struct SystemControlBlock final {
         /// @brief Default constructor
         SystemHandlerControlState()
             : whole{0} {}
+        /// Copy constructor from another instance
         SystemHandlerControlState(SystemHandlerControlState const& other)
             : whole{other.whole} {}
+        /// Copy constructor from volatile register
         SystemHandlerControlState(SystemHandlerControlState volatile& other)
             : whole{other.whole} {}
         /// @brief The bit field for the System Handler Control State Register
@@ -268,8 +270,10 @@ struct SystemControlBlock final {
         /// @brief Default constructor
         ConfigurationFaultStatus()
             : whole{0} {}
+        /// Copy constructor from another instance
         ConfigurationFaultStatus(ConfigurationFaultStatus const& other)
             : whole{other.whole} {}
+        /// Copy constructor from volatile register
         ConfigurationFaultStatus(ConfigurationFaultStatus volatile& other)
             : whole{other.whole} {}
         /// @brief The bit field for the Configuration Fault Status Register
@@ -316,10 +320,13 @@ struct SystemControlBlock final {
 
     /// The Hard Fault Status Register (HFSR)
     struct HardFaultStatus final {
+        /// Default constructor - initializes to zero
         HardFaultStatus()
             : whole{0} {}
+        /// Copy constructor from another instance
         HardFaultStatus(HardFaultStatus const& other)
             : whole{other.whole} {}
+        /// Copy constructor from volatile register
         HardFaultStatus(HardFaultStatus volatile& other)
             : whole{other.whole} {}
         /// @brief The bit field for the Hard Fault Status Register
@@ -344,10 +351,13 @@ struct SystemControlBlock final {
 
     /// The Debug Fault Register (DFR)
     struct DebugFaultStatus final {
+        /// Default constructor - initializes to zero
         DebugFaultStatus()
             : whole{0} {}
+        /// Copy constructor from another instance
         DebugFaultStatus(DebugFaultStatus const& other)
             : whole{other.whole} {}
+        /// Copy constructor from volatile register
         DebugFaultStatus(DebugFaultStatus volatile& other)
             : whole{other.whole} {}
         /// @brief The bit field for the Debug Fault Register
@@ -373,7 +383,7 @@ struct SystemControlBlock final {
 
     /// The Memory Management Fault Address Register (MMFAR)
     struct MemoryManagementFaultAddress final {
-        std::uintptr_t address;
+        std::uintptr_t address;    ///< Address that caused the MemManage fault
     };
 #if defined(__arm__)
     static_assert(sizeof(MemoryManagementFaultAddress) == sizeof(std::uint32_t), "Must be exactly this size");
@@ -389,10 +399,13 @@ struct SystemControlBlock final {
 
     /// The Co Processor Access Control Register
     struct CoProcessorAccessControl final {
+        /// Default constructor - initializes to zero
         CoProcessorAccessControl()
             : whole{0} {}
+        /// Copy constructor from another instance
         CoProcessorAccessControl(CoProcessorAccessControl const& other)
             : whole{other.whole} {}
+        /// Copy constructor from volatile register
         CoProcessorAccessControl(CoProcessorAccessControl volatile& other)
             : whole{other.whole} {}
         /// @brief The access values for the register

modules/cortex/include/cortex/peripherals/SystemTick.hpp

@@ -15,35 +15,43 @@ struct SystemTick final {
     /// @brief System Timer Control and Status Register
     /// @details Controls the SysTick timer operation and reports its status
     struct ControlStatus final {
+        /// Default constructor - initializes to zero
         ControlStatus()
             : whole{0} {}
+        /// Copy constructor from another instance
         ControlStatus(ControlStatus const& other)
             : whole{other.whole} {}
+        /// Copy constructor from volatile register
         ControlStatus(ControlStatus volatile& other)
             : whole{other.whole} {}
         /// @brief Bit field layout for the Control and Status register
         struct Fields final {
-            std::uint32_t enable              : 1U;
-            std::uint32_t interrupt           : 1U;
-            std::uint32_t use_processor_clock : 1U;
+            std::uint32_t enable              : 1U;     ///< Enable SysTick counter
+            std::uint32_t interrupt           : 1U;     ///< Enable SysTick interrupt
+            std::uint32_t use_processor_clock : 1U;     ///< Use processor clock (vs external reference)
             std::uint32_t                     : 13U;    ///< Reserved field
-            std::uint32_t counted_down        : 1U;
+            std::uint32_t counted_down        : 1U;     ///< Counter counted to zero since last read
             std::uint32_t                     : 15U;    ///< Reserved field
         };
         union {
             Fields bits;
             std::uint32_t whole;
         };
+        /// Assignment from copy back to volatile registers
         void operator=(ControlStatus const& other) volatile { whole = other.whole; }
+        /// Copy from volatile register to local copy
         void operator=(ControlStatus volatile& other) { whole = other.whole; }
     };
     /// @brief System Timer Reload Value Register
     /// @details Specifies the reload value for the SysTick counter
     struct Reload final {
+        /// Default constructor - initializes to zero
         Reload()
             : whole{0} {}
+        /// Copy constructor from another instance
         Reload(Reload const& other)
             : whole{other.whole} {}
+        /// Copy constructor from volatile register
         Reload(Reload volatile& other)
             : whole{other.whole} {}
         /// @brief Bit field layout for the Reload register
@@ -55,37 +63,44 @@ struct SystemTick final {
             Fields bits;
             std::uint32_t whole;
         };
+        /// Assignment from copy back to volatile registers
         void operator=(Reload const& other) volatile { whole = other.whole; }
+        /// Copy from volatile register to local copy
         void operator=(Reload volatile& other) { whole = other.whole; }
     };
     /// The Calibration Registers
     struct Calibration final {
+        /// Default constructor - initializes to zero
         Calibration()
             : whole{0} {}
+        /// Copy constructor from another instance
         Calibration(Calibration const& other)
             : whole{other.whole} {}
+        /// Copy constructor from volatile register
         Calibration(Calibration volatile& other)
             : whole{other.whole} {}
         /// @brief Bit field layout for the Calibration register
         struct Fields final {
             std::uint32_t ten_millisecond_count : 24U;    ///< The number of reference clocks per 10ms
             std::uint32_t                       : 6U;     ///< Reserved field
-            std::uint32_t skew                  : 1U;     ///< Indicates if the
-            std::uint32_t no_reference          : 1U;
+            std::uint32_t skew                  : 1U;     ///< Indicates if the calibration value is inexact
+            std::uint32_t no_reference          : 1U;     ///< No reference clock provided
         };
         union {
             Fields bits;
             std::uint32_t whole;
         };
+        /// Assignment from copy back to volatile registers
         void operator=(Calibration const& other) volatile { whole = other.whole; }
+        /// Copy from volatile register to local copy
         void operator=(Calibration volatile& other) { whole = other.whole; }
     };
 
     // ===================================
-    ControlStatus control_status;
-    Reload reload;
-    std::uint32_t current;    ///< The current countdown value. If written to it will clear it.
-    Calibration calibration;
+    ControlStatus control_status;    ///< Control and status register
+    Reload reload;                   ///< Reload value register
+    std::uint32_t current;           ///< The current countdown value. If written to it will clear it.
+    Calibration calibration;         ///< Calibration value register
     // ===================================
 };
 static_assert(offsetof(SystemTick, current) == 0x08, "Must be at this offset");

modules/cortex/include/cortex/peripherals/TightlyCoupledMemory.hpp

@@ -11,10 +11,13 @@ namespace peripherals {
 /// @details Represents the TCM configuration register in ARM Cortex-M processors.
 /// TCM provides low-latency memory directly coupled to the processor for performance-critical code and data.
 struct TightlyCoupledMemory final {
+    /// Default constructor - initializes to zero
     TightlyCoupledMemory()
         : whole{0} {}
+    /// Copy constructor from another instance
     TightlyCoupledMemory(TightlyCoupledMemory const& other)
         : whole{other.whole} {}
+    /// Copy constructor from volatile register
     TightlyCoupledMemory(TightlyCoupledMemory volatile& other)
         : whole{other.whole} {}
     /// @brief Bit field layout for the TCM control register

modules/cortex/include/cortex/registers.hpp

@@ -45,6 +45,8 @@ struct ProgramStatus final {
         std::uint32_t top    : 2U;     //!< Top ICI/IT Bits
         std::uint32_t        : 5U;     ///< Reserved field
 
+        /// Gets the combined ICI/IT state value
+        /// @return The 8-bit ICI/IT state (top 2 bits | bottom 6 bits)
         inline std::uint32_t get(void) const {
             std::uint32_t tmp = static_cast<uint32_t>(top << 6U);
             tmp |= bottom;
@@ -57,12 +59,12 @@ struct ProgramStatus final {
 struct Masks final {
     /// The Priority Mask Register (PRIMASK)
     struct Priority final {
-        std::uint32_t mask : 1;
+        std::uint32_t mask : 1;     ///< Disable all interrupts except NMI and HardFault
         std::uint32_t      : 31;    ///< Reserved field
     };
     /// The Fault Mask Register (FAULTMASK)
     struct Fault final {
-        std::uint32_t mask : 1;
+        std::uint32_t mask : 1;     ///< Disable all interrupts except NMI
         std::uint32_t      : 31;    ///< Reserved field
     };
     /// The Base Priority Mask Register (BASEPRI)

modules/cortex/include/cortex/semihosting.hpp

@@ -44,74 +44,72 @@ enum class Mode : std::uint32_t {
     AppendPlusBinary = 11,
 };
 
-/// Checks if the debugger is connected.
+/// @brief Checks if the debugger is connected.
 bool IsConnected(void);
 
-/// Opens a file and returns a handle.
+/// @brief Opens a file and returns a handle.
 /// @param name The span of the name of the file to open.
 /// @param mode The mode to open the file in.
 Handle Open(core::Span<char const> name, Mode mode);
 
-/// Closes a file.
+/// @brief Closes a file.
 /// @param handle The handle of the file to close.
 /// @return 0 on success, -1 on error.
 Result Close(Handle handle);
 
-/// Writes data to a file.
+/// @brief Writes data to a file.
 /// @param handle The handle of the file to write to.
-/// @param buffer The data to write.
-/// @param len The length of the data to write.
+/// @param buffer The span over the buffer to write from
 /// @return The number of bytes written, or -1 on error.
 Result Write(Handle handle, core::Span<char const> buffer);
 
-/// Writes a single character to a file
+/// @brief Writes a single character to a file
 /// @param c The character to write.
 void Write(char c);
 
-/// Writes a string to a file.
+/// @brief Writes a string to a file.
 /// @param string The string to write.
 void Write(const char string[]);
 
-/// Reads data from a file.
+/// @brief Reads data from a file.
 /// @param handle The handle of the file to read from.
-/// @param buffer The buffer to read the data into.
-/// @param len The length of the data to read.
+/// @param buffer The span over the buffer to read the data into
 /// @return The number of bytes read, or -1 on error.
 Result Read(Handle handle, core::Span<char> buffer);
 
-/// Reads a character from a file.
+/// @brief Reads a character from a file.
 char Read(void);
 
-/// Checks if a value is an error.
+/// @brief Checks if a value is an error.
 /// @return True if the value is an error, false otherwise.
 bool IsError(int32_t value);
 
-/// Checks if a file handle is a TTY.
+/// @brief Checks if a file handle is a TTY.
 /// @param handle The handle of the file to check.
 /// @return True if the file is a TTY, false otherwise.
 bool IsTTY(int handle);
 
-/// Seeks to a position in a file.
+/// @brief Seeks to a position in a file.
 /// @param handle The handle of the file to seek in.
 /// @param position The position to seek to.
 /// @return The new position on success, or -1 on error.
 Result Seek(Handle handle, uint32_t position);
 
-/// Gets the length of a file.
+/// @brief Gets the length of a file.
 /// @param handle The handle of the file to get the length of.
 /// @return The length of the file, or -1 on error.
 int32_t Length(Handle handle);
 
-/// Gets A temporary name for a file.
-/// @param name[out] The location to store the name of the file
+/// @brief Gets A temporary name for a file.
+/// @param name The location to store the name of the file
 /// @param id The ID of the temporary file.
 Result TempName(core::Span<char const> name, uint32_t id);
 
-/// Removes a file from the Host File System
+/// @brief Removes a file from the Host File System
 /// @param name The span of the name of the file to remove
 Result Remove(core::Span<char const> name);
 
-/// Renames a file on the Host File System
+/// @brief Renames a file on the Host File System
 /// @param old_file The span of the current file name
 /// @param new_file The span of the new file name
 /// @return 0 on success, -1 on error
@@ -136,10 +134,10 @@ uint32_t GetCommandLine(core::Span<char> buffer);
 
 /// @brief Information about the heap and stack blocks
 struct BlockInfo {
-    uint32_t heap_base;
-    uint32_t heap_limit;
-    uint32_t stack_base;
-    uint32_t stack_limit;
+    uint32_t heap_base;      ///< Base address of heap
+    uint32_t heap_limit;     ///< Limit address of heap
+    uint32_t stack_base;     ///< Base address of stack
+    uint32_t stack_limit;    ///< Limit address of stack
 };
 
 /// @param[out] info The block information to fill in