Improve README and doxygen comments

include/sta/assert.hpp

@@ -1,17 +1,19 @@
 /**
  * @brief Assertion handling.
  *
- * Define **STA_ASSERT_ENABLE** in `<sta/config.hpp>` to enable module.
+ * Configuration:
+ *     STA_ASSERT_ENABLE:   Enable module
+ *     STA_ASSERT_DISABLE:  Forces module off when defined
+ *     STA_HALT:            Override function called after failed asserts
+ *     DEBUG:               Automatically enables module when defined
+ *     NDEBUG:              Forces module off when defined
  *
- * When **DEBUG** is defined the module will be enabled automatically.
- * Defining **NDEBUG** or **STA_ASSERT_DISABLE** always overrides enabling the module.
+ * Both `sta::assert_failed` and `sta::assert_halt` provide weak definitions and
+ * can be overridden by the application. `sta::assert_halt` is only called
+ * via the **STA_HALT** macro which can also be provided by the application.
  *
- * Both `assert_failed` and `assert_halt` provide weak definitions and
- * can be overridden by the application. `assert_halt` is only called
- * via the STA_HALT macro which can also be provided by the application.
- *
- * The default implementation of `assert_failed` uses **STA_DEBUG_PRINT** internally
- * and will not generate any output if `<sta/debug_serial.hpp> is disabled.
+ * The default implementation of `sta::assert_failed` uses **STA_DEBUG_PRINT** internally
+ * and will not generate any output if the **DEBUG_SERIAL** module is disabled.
  */
 #ifndef STA_ASSERT_HPP
 #define STA_ASSERT_HPP

include/sta/debug_serial.hpp

@@ -1,12 +1,13 @@
 /**
  * @brief Debug output via UART.
  *
- * Define **STA_DEBUG_SERIAL_ENABLE** in `<sta/config.hpp>` to enable module.
+ * Configuration:
+ *     STA_DEBUG_SERIAL_ENABLE:     Enable module
+ *     STA_DEBUG_SERIAL_DISABLE:    Forces module off when defined
+ *     DEBUG:                       Automatically enables module when defined
+ *     NDEBUG:                      Forces module off when defined
  *
- * When **DEBUG** is defined the module will be enabled automatically.
- * Defining **NDEBUG** or **STA_DEBUG_SERIAL_DISABLE** always overrides enabling the module.
- *
- * The sta::DebugSerial instance must be provided.
+ * The `sta::DebugSerial` instance must be provided.
  * NOTE: Include this header before the definition because
  *       the default internal linkage of const namespace variables
  *       will cause undefined reference errors otherwise.

include/sta/endian.hpp

@@ -1,3 +1,6 @@
+/**
+ * @brief Helper macros for managing endian handling.
+ */
 #ifndef STA_ENDIAN_HPP
 #define STA_ENDIAN_HPP
 

include/sta/enum_flags.hpp

@@ -1,3 +1,6 @@
+/**
+ * @brief Helper for using enum values as flags.
+ */
 #ifndef STA_ENUM_FLAGS_HPP
 #define STA_ENUM_FLAGS_HPP
 

include/sta/enum_flags.tpp

@@ -1,3 +1,6 @@
+/**
+ * @brief Template class implementation for `EnumFlags<T>`.
+ */
 #ifndef STA_ENUM_FLAGS_TPP
 #define STA_ENUM_FLAGS_TPP
 

include/sta/hal/delay.hpp

@@ -3,10 +3,10 @@
  *
  * Configuration:
  *     STA_HAL_DELAY_ENABLE: Enable module
- *     STA_HAL_DELAY_US_TIM: HAL TIM instance for `delayUs()`
+ *     STA_HAL_DELAY_US_TIM: 1 MHz TIM instance used by `sta::delayUs`
  *
- * NOTE: Don't forget to start TIM. When using startup system task this
- *       is automatically handled.
+ * 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_HAL_DELAY_HPP
 #define STA_HAL_DELAY_HPP
@@ -14,6 +14,8 @@
 #include <sta/config.hpp>
 #ifdef STA_HAL_DELAY_ENABLE
 
+#include <cstdint>
+
 
 namespace sta
 {