Cleanup doxygen

2025-08-05 18:21:54 +00:00 · 2023-01-31 21:14:02 +01:00
parent a7466d6417
commit 4204c028a2
24 changed files with 89 additions and 154 deletions
--- a/include/sta/assert.hpp
+++ b/include/sta/assert.hpp
@@ -1,6 +1,11 @@
 /**
 * @file
 * @brief Assertion handling.
+ *
+ * Configuration:
+ *   * STA_ASSERT_FORCE:    Ignore debug defines and always enable assertions
+ *   * DEBUG:               Enables assertions when defined
+ *   * NDEBUG:              Disables assertions when defined (overrides DEBUG)
 */
 #ifndef STA_CORE_ASSERT_HPP
 #define STA_CORE_ASSERT_HPP
@@ -22,52 +27,24 @@
 * @brief Assertion handling.
 */

-#ifdef DOXYGEN
-/**
- * @def STA_ASSERT_ENABLE
- * @brief Enable module.
- *
- * Automatically defined if DEBUG is defined.
- * Automatically disabled if NDEBUG is defined.
- *
- * @ingroup staCoreBuildConfig
- */
-#  define STA_ASSERT_ENABLE
-
-/**
- * @def STA_ASSERT_DISABLE
- * @brief Force disable module.
- *
- * Overrides STA_ASSERT_ENABLE option.
- *
- * @ingroup staCoreBuildConfig
- */
-#  define STA_ASSERT_DISABLE
-#endif // DOXYGEN
-

 #include <sta/config.hpp>

-#ifdef DEBUG
-#  ifndef STA_ASSERT_ENABLE
-#    define STA_ASSERT_ENABLE
-#  endif // !STA_ASSERT_ENABLE
-#endif // DEBUG
-
-#if defined(NDEBUG) || defined(STA_ASSERT_DISABLE)
-#  ifdef STA_ASSERT_ENABLE
-#    undef STA_ASSERT_ENABLE
-#  endif // STA_ASSERT_ENABLE
-#endif // NDEBUG || STA_ASSERT_DISABLE
+// Determine if module should be enabled
+// Condition:
+//     STA_ASSERT_FORCE is defined
+//   or
+//     DEBUG is defined but not NDEBUG
+#ifdef STA_ASSERT_FORCE
+#  define STA_ASSERT_ENABLED
+#else // !STA_ASSERT_FORCE
+#  if defined(DEBUG) && !defined(NDEBUG)
+#    define STA_ASSERT_ENABLED
+#  endif // DEBUG && !NDEBUG
+#endif // !STA_ASSERT_FORCE


-// Show enabled module in doxygen output
-#ifdef DOXYGEN
-#  define STA_ASSERT_ENABLE
-#endif // DOXYGEN
-
-
-#ifdef STA_ASSERT_ENABLE
+#if defined(STA_ASSERT_ENABLED) || defined(DOXYGEN)

 #include <cstdint>

@@ -152,7 +129,7 @@ namespace sta

 #  define STA_ASSERT_EXTRA(expr)				expr;

-#else // !STA_ASSERT_ENABLE
+#else // !STA_ASSERT_ENABLED

 #  define STA_ASSERT(expr)                      ((void)0)
 #  define STA_ASSERT_MSG(expr, msg)             ((void)0)
@@ -161,7 +138,7 @@ namespace sta

 #  define STA_ASSERT_EXTRA(expr)				((void)0)

-#endif // !STA_ASSERT_ENABLE
+#endif // !STA_ASSERT_ENABLED


 #endif // STA_CORE_ASSERT_HPP
--- a/include/sta/atomic/mutex.hpp
+++ b/include/sta/atomic/mutex.hpp
@@ -1,14 +1,19 @@
 /**
+ * @file
 * @brief Atomic mutex implementation.
 *
 * Configuration:
- *     STA_ATOMIC_ENABLE: Enable module
+ *     STA_STDLIB_HAS_ATOMIC: Enable module
 */
 #ifndef STA_CORE_ATOMIC_MUTEX_HPP
 #define STA_CORE_ATOMIC_MUTEX_HPP

 #include <sta/config.hpp>
-#ifdef STA_ATOMIC_ENABLE
+#ifdef STA_STDLIB_HAS_ATOMIC
+#  define STA_ATOMIC_ENABLED
+#endif // STA_STDLIB_HAS_ATOMIC
+
+#if defined(STA_ATOMIC_ENABLED) || defined(DOXYGEN)

 #include <sta/mutex.hpp>

@@ -34,6 +39,6 @@ namespace sta
 } // namespace sta


-#endif // STA_ATOMIC_ENABLE
+#endif // STA_ATOMIC_ENABLED

 #endif // STA_CORE_ATOMIC_MUTEX_HPP
--- a/include/sta/atomic/signal.hpp
+++ b/include/sta/atomic/signal.hpp
@@ -1,14 +1,19 @@
 /**
+ * @file
 * @brief Atomic signal implementation.
 *
 * Configuration:
- *     STA_ATOMIC_ENABLE: Enable module
+ *     STA_STDLIB_HAS_ATOMIC: Enable module
 */
 #ifndef STA_CORE_ATOMIC_SIGNAL_HPP
 #define STA_CORE_ATOMIC_SIGNAL_HPP

 #include <sta/config.hpp>
-#ifdef STA_ATOMIC_ENABLE
+#ifdef STA_STDLIB_HAS_ATOMIC
+#  define STA_ATOMIC_ENABLED
+#endif // STA_STDLIB_HAS_ATOMIC
+
+#if defined(STA_ATOMIC_ENABLED) || defined(DOXYGEN)

 #include <sta/signal.hpp>

@@ -36,6 +41,6 @@ namespace sta
 } // namespace sta


-#endif // STA_ATOMIC_ENABLE
+#endif // STA_ATOMIC_ENABLED

 #endif // STA_CORE_ATOMIC_SIGNAL_HPP
--- a/include/sta/can/iter.hpp
+++ b/include/sta/can/iter.hpp
@@ -1,3 +1,7 @@
+/**
+ * @file
+ * @brief Custom iterators for CAN controllers.
+ */
 #ifndef STA_CORE_CAN_ITER_HPP
 #define STA_CORE_CAN_ITER_HPP

--- a/include/sta/debug_serial.hpp
+++ b/include/sta/debug_serial.hpp
@@ -3,10 +3,10 @@
 * @brief Debug output via UART.
 *
 * Configuration:
- *     STA_DEBUG_SERIAL_UART:   UART interface for output
- *     STA_DEBUG_SERIAL_FORCE:  Ignore debug defines and always enable output
- *     DEBUG:                   Enables output when defined
- *     NDEBUG:                  Disables output when defined (overrides DEBUG)
+ *   * STA_DEBUG_SERIAL_UART:   UART interface for output
+ *   * STA_DEBUG_SERIAL_FORCE:  Ignore debug defines and always enable output
+ *   * DEBUG:                   Enables output when defined
+ *   * NDEBUG:                  Disables output when defined (overrides DEBUG)
 */
 #ifndef STA_CORE_DEBUG_SERIAL_HPP
 #define STA_CORE_DEBUG_SERIAL_HPP
@@ -17,28 +17,6 @@
 * @brief Debug serial output.
 */

-#ifdef DOXYGEN
-/**
- * @def STA_DEBUG_SERIAL_UART
- * @brief UART interface for debug output.
- *
- * @ingroup staCoreBuildConfig
- */
-#  define STA_DEBUG_SERIAL_UART
-
-/**
- * @def STA_DEBUG_SERIAL_FORCE
- * @brief Force enable module.
- *
- * Enables debug output even if NDEBUG is defined
- * or DEBUG is not defined.
- *
- * @ingroup staCoreBuildConfig
- */
-#  define STA_DEBUG_SERIAL_FORCE
-#endif // DOXYGEN
-
-
 #include <sta/config.hpp>

 // Determine if module should be enabled
@@ -57,14 +35,7 @@
 #  endif // !STA_DEBUG_SERIAL_FORCE
 #endif // STA_DEBUG_SERIAL_UART

-
-// Show enabled module in doxygen output
-#ifdef DOXYGEN
-#  define STA_DEBUG_SERIAL_ENABLED
-#endif // DOXYGEN
-
-
-#ifdef STA_DEBUG_SERIAL_ENABLED
+#if defined(STA_DEBUG_SERIAL_ENABLED) || defined(DOXYGEN)

 #include <sta/printable_uart.hpp>

--- a/include/sta/gpio_pin.hpp
+++ b/include/sta/gpio_pin.hpp
@@ -1,4 +1,5 @@
 /**
+ * @file
 * @brief GPIO pin interface definitions.
 */
 #ifndef STA_CORE_GPIO_PIN_HPP
--- a/include/sta/mutex.hpp
+++ b/include/sta/mutex.hpp
@@ -1,4 +1,5 @@
 /**
+ * @file
 * @brief Mutex interface definition.
 */
 #ifndef STA_CORE_MUTEX_HPP
--- a/include/sta/printf.hpp
+++ b/include/sta/printf.hpp
@@ -1,29 +1,14 @@
 /**
 * @file
 * @brief Compatibility layer for different printf implementations.
+ *
+ * Configuration:
+ *   * STA_PRINTF_USE_STDLIB:   Use printf implementation from standard library
+ *   * STA_PRINTF_USE_MPALAND:  Use printf implementation from Marco Paland
 */
 #ifndef STA_CORE_PRINTF_HPP
 #define STA_CORE_PRINTF_HPP

-#ifdef DOXYGEN
-/**
- * @def STA_PRINTF_USE_STDLIB
- * @brief Use printf implementation from STD library.
- *
- * @ingroup staCoreBuildConfig
- */
-#  define STA_PRINTF_USE_STDLIB
-
-/**
- * @def STA_PRINTF_USE_MPALAND
- * @brief Use printf implementation from Marco Paland.
- *
- * @ingroup staCoreBuildConfig
- */
-#  define STA_PRINTF_USE_MPALAND
-#endif // DOXYGEN
-
-
 #include <sta/config.hpp>

 #if !defined(STA_PRINTF_USE_STDLIB) && !defined(STA_PRINTF_USE_MPALAND)
--- a/include/sta/signal.hpp
+++ b/include/sta/signal.hpp
@@ -1,4 +1,5 @@
 /**
+ * @file
 * @brief Signal interface definition.
 */
 #ifndef STA_CORE_SIGNAL_HPP
--- a/include/sta/stm32/can.hpp
+++ b/include/sta/stm32/can.hpp
@@ -1,6 +1,9 @@
 /**
 * @file
 * @brief Implementation of CanController using STM32 HAL.
+ *
+ * Configuration:
+ *   * STA_STM32_CAN_GLOBAL: Create global CanBus object using this CAN instance
 */
 #ifndef STA_CORE_STM32_CAN_HPP
 #define STA_CORE_STM32_CAN_HPP
@@ -13,18 +16,6 @@
 * Check @ref stm32BuildConfig for configuration options.
 */

-#ifdef DOXYGEN
-/**
- * @def STA_STM32_CAN_GLOBAL
- * @brief Create global CanBus object using this CAN instance.
- *
- * @ingroup stm32BuildConfig
- */
-#  define STA_STM32_CAN_GLOBAL
-#endif // DOXYGEN
-
-
-
 // Only enable module on STM32 platform w/ HAL CAN module enabled
 #include <sta/config.hpp>
 #ifdef STA_PLATFORM_STM32
@@ -35,7 +26,7 @@
 #endif // STA_PLATFORM_STM32


-#ifdef STA_STM32_CAN_ENABLED
+#if defined(STA_STM32_CAN_ENABLED) || defined(DOXYGEN)

 #include <sta/can/controller.hpp>

@@ -104,7 +95,7 @@ namespace sta



-#ifdef STA_STM32_CAN_GLOBAL
+#if defined(STA_STM32_CAN_GLOBAL) || DOXYGEN
 	/**
 	 * @brief Global CAN instance.
 	 *
--- a/include/sta/stm32/clocks.hpp
+++ b/include/sta/stm32/clocks.hpp
@@ -26,7 +26,7 @@

 // Only enable module on STM32 platform
 #include <sta/config.hpp>
-#ifdef STA_PLATFORM_STM32
+#if defined(STA_PLATFORM_STM32) || defined(DOXYGEN)

 #include <sta/stm32/hal.hpp>

--- a/include/sta/stm32/delay.hpp
+++ b/include/sta/stm32/delay.hpp
@@ -1,6 +1,12 @@
 /**
 * @file
 * @brief Delay functions.
+ *
+ * Configuration:
+ *   * STA_STM32_DELAY_US_TIM: 1 MHz TIM instance used by sta::delayUs
+ *
+ * NOTE: TIM time base must be started before use of sta::delayUs by calling sta::initHAL.
+ *       When using startup system task this is handled automatically.
 */
 #ifndef STA_CORE_STM32_DELAY_HPP
 #define STA_CORE_STM32_DELAY_HPP
@@ -11,23 +17,9 @@
 * @brief STM32 Delay module.
 */

-#ifdef DOXYGEN
-/**
- * @def STA_STM32_DELAY_US_TIM
- * @brief 1 MHz TIM instance used by sta::delayUs.
- *
- * NOTE: TIM time base must be started before use of sta::delayUs by calling sta::initHAL.
- *       When using startup system task this is handled automatically.
- *
- * @ingroup stm32BuildConfig
- */
-#  define STA_STM32_DELAY_US_TIM
-#endif // DOXYGEN
-
-
 // Only enable module on STM32 platform
 #include <sta/config.hpp>
-#ifdef STA_PLATFORM_STM32
+#if defined(STA_PLATFORM_STM32) || defined(DOXYGEN)

 #include <cstdint>

@@ -43,7 +35,7 @@ namespace sta
 	 */
 	void delayMs(uint32_t ms);

-#ifdef STA_STM32_DELAY_US_TIM
+#if defined(STA_STM32_DELAY_US_TIM) || defined(DOXYGEN)
 	/**
 	 * @brief Microsecond delay.
 	 *
--- a/include/sta/stm32/gpio_pin.hpp
+++ b/include/sta/stm32/gpio_pin.hpp
@@ -11,17 +11,6 @@
 * @brief STM32 GPIO module.
 */

-#ifdef DOXYGEN
-/**
- * @def STA_STM32_GPIO_ENABLE
- * @brief Enable module.
- *
- * @ingroup stm32BuildConfig
- */
-#  define STA_STM32_GPIO_ENABLE
-#endif // DOXYGEN
-
-
 // Only enable module on STM32 platform w/ HAL GPIO module enabled
 #include <sta/config.hpp>
 #ifdef STA_PLATFORM_STM32
@@ -32,7 +21,7 @@
 #endif // STA_PLATFORM_STM32


-#ifdef STA_STM32_GPIO_ENABLED
+#if defined(STA_STM32_GPIO_ENABLED) || defined(DOXYGEN)

 #include <sta/gpio_pin.hpp>

--- a/include/sta/stm32/hal.hpp
+++ b/include/sta/stm32/hal.hpp
@@ -1,3 +1,7 @@
+/**
+ * @file
+ * @brief Generic header for including the STM32 HAL headers.
+ */
 #ifndef STA_CORE_STM32_HAL_HPP
 #define STA_CORE_STM32_HAL_HPP

--- a/include/sta/stm32/mcu/STM32F411xE.hpp
+++ b/include/sta/stm32/mcu/STM32F411xE.hpp
@@ -1,4 +1,5 @@
 /**
+ * @file
 * @brief Configuration for STM32F411xE family.
 */
 #ifndef STA_CORE_STM32_MCU_STM32F411xE_HPP
--- a/include/sta/stm32/mcu/STM32F413xx.hpp
+++ b/include/sta/stm32/mcu/STM32F413xx.hpp
@@ -1,4 +1,5 @@
 /**
+ * @file
 * @brief Configuration for STM32F413xx family.
 */
 #ifndef STA_CORE_STM32_MCU_STM32F413xx_HPP
--- a/include/sta/stm32/mcu/common.hpp
+++ b/include/sta/stm32/mcu/common.hpp
@@ -1,4 +1,5 @@
 /**
+ * @file
 * @brief Common configuration for STM32 MCUs
 */
 #ifndef STA_CORE_STM32_MCU_COMMON_HPP
--- a/include/sta/stm32/spi.hpp
+++ b/include/sta/stm32/spi.hpp
@@ -24,8 +24,7 @@
 #  endif // HAL_SPI_MODULE_ENABLED
 #endif // STA_PLATFORM_STM32

-
-#ifdef STA_STM32_SPI_ENABLED
+#if defined(STA_STM32_SPI_ENABLED) || defined(DOXYGEN)

 #include <sta/spi/device.hpp>
 #include <sta/spi/interface.hpp>
--- a/include/sta/stm32/uart.hpp
+++ b/include/sta/stm32/uart.hpp
@@ -22,7 +22,7 @@
 #endif // STA_PLATFORM_STM32


-#ifdef STA_STM32_UART_ENABLED
+#if defined(STA_STM32_UART_ENABLED) || defined(DOXYGEN)

 #include <sta/uart.hpp>

--- a/include/sta/time.hpp
+++ b/include/sta/time.hpp
@@ -1,4 +1,5 @@
 /**
+ * @file
 * @brief Signatures for time related functions.
 */
 #ifndef STA_CORE_TIME_HPP