Improve doxygen documentation

README.md

@@ -1,5 +1,8 @@
 # STA Core library
 
+![pre-release v0.1.0](https://img.shields.io/static/v1?label=pre-release&message=v0.1.0&color=orange&logo=git)
+![Standard: C++11](https://img.shields.io/static/v1?label=standard&message=C%2B%2B11&color=blue&logo=cplusplus)
+
 Collection of useful stuff.
 
 

include/sta/hal/clocks.hpp

@@ -1,9 +1,28 @@
 /**
+ * @file
  * @brief Helper macros for HAL clock queries.
  */
 #ifndef STA_HAL_CLOCKS_HPP
 #define STA_HAL_CLOCKS_HPP
 
+/**
+ * @defgroup hal HAL
+ * @brief HAL base implementations.
+ */
+
+/**
+ * @defgroup halBuildConfig Build config
+ * @ingroup hal
+ * @brief Build configuration options.
+ */
+
+/**
+ * @defgroup halClocks Clocks
+ * @ingroup hal
+ * @brief HAL clock queries.
+ * @{
+ */
+
 #include <sta/config.hpp>
 #include <sta/hal.hpp>
 
@@ -57,4 +76,6 @@
 #define STA_HAL_GET_HANDLE_PCLK_FREQ_FN(handle) _STA_HAL_GET_PCLK_FREQ_FN(_STA_HAL_PCLK_IDX_MAP(handle))
 
 
+/** @} */
+
 #endif // STA_HAL_CLOCKS_HPP

include/sta/hal/delay.hpp

@@ -1,16 +1,38 @@
 /**
+ * @file
  * @brief Delay functions.
- *
- * Configuration:
- *     STA_HAL_DELAY_ENABLE: Enable module
- *     STA_HAL_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_HAL_DELAY_HPP
 #define STA_HAL_DELAY_HPP
 
+/**
+ * @defgroup halDelay Delay
+ * @ingroup hal
+ * @brief HAL Delay module
+ */
+
+#ifdef DOXYGEN
+/**
+ * @def STA_HAL_DELAY_ENABLE
+ * @brief Enable module.
+ *
+ * @ingroup halBuildConfig
+ */
+#  define STA_HAL_DELAY_ENABLE
+
+/**
+ * @def STA_HAL_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 halBuildConfig
+ */
+#  define STA_HAL_DELAY_US_TIM
+#endif // DOXYGEN
+
+
 #include <sta/config.hpp>
 #ifdef STA_HAL_DELAY_ENABLE
 
@@ -23,6 +45,8 @@ namespace sta
 	 * @brief Millisecond delay.
 	 *
 	 * @param ms    Milliseconds
+	 *
+	 * @ingroup halDelay
 	 */
 	void delayMs(uint32_t ms);
 
@@ -31,6 +55,8 @@ namespace sta
 	 * @brief Microsecond delay.
 	 *
 	 * @param us    Microseconds
+	 *
+	 * @ingroup halDelay
 	 */
 	void delayUs(uint32_t us);
 #endif // STA_HAL_DELAY_US_TIM
@@ -40,3 +66,4 @@ namespace sta
 #endif // STA_HAL_DELAY_TIM
 
 #endif // STA_HAL_DELAY_HPP
+/** @} */

include/sta/hal/gpio_pin.hpp

@@ -1,12 +1,27 @@
 /**
+ * @file
  * @brief Wrapper for HAL GPIO pins.
- *
- * Configuration:
- *     STA_HAL_GPIO_ENABLE: Enable module
  */
 #ifndef STA_HAL_GPIO_PIN_HPP
 #define STA_HAL_GPIO_PIN_HPP
 
+/**
+ * @defgroup halGPIO GPIO
+ * @ingroup hal
+ * @brief HAL GPIO module
+ */
+
+#ifdef DOXYGEN
+/**
+ * @def STA_HAL_GPIO_ENABLE
+ * @brief Enable module.
+ *
+ * @ingroup halBuildConfig
+ */
+#  define STA_HAL_GPIO_ENABLE
+#endif // DOXYGEN
+
+
 #include <sta/config.hpp>
 #ifdef STA_HAL_GPIO_ENABLE
 
@@ -18,6 +33,8 @@ namespace sta
 {
 	/**
 	 * @brief Container for HAL GPIO Pin objects.
+	 *
+	 * @ingroup halGPIO
 	 */
 	class HalGpioPin : public GpioPin
 	{
@@ -40,6 +57,8 @@ namespace sta
  * @brief Create HalGpioPin object from pin label.
  *
  * @param label     Pin label
+ *
+ * @ingroup halGPIO
  */
 #define STA_HAL_GPIO_PIN(label) sta::HalGpioPin{label##_GPIO_Port, label##_Pin}
 

include/sta/hal/init.hpp

@@ -1,4 +1,5 @@
 /**
+ * @file
  * @brief Global HAL initialization.
  */
 #ifndef STA_HAL_INIT_HPP
@@ -9,6 +10,8 @@ namespace sta
 {
 	/**
 	 * @brief Initialize global HAL objects.
+	 *
+	 * @ingroup hal
 	 */
 	void initHAL();
 } // namespace sta

include/sta/hal/spi.hpp

@@ -1,19 +1,34 @@
 /**
+ * @file
  * @brief Implementations for `SpiInterface` and `SpiDevice` using HAL.
- *
- * Configuration:
- *     STA_HAL_SPI_ENABLE: Enable module
- *
- * Requires **HAL_GPIO** module.
  */
 #ifndef STA_HAL_SPI_HPP
 #define STA_HAL_SPI_HPP
 
+/**
+ * @defgroup halSPI SPI
+ * @ingroup hal
+ * @brief HAL SPI module.
+ */
+
+#ifdef DOXYGEN
+/**
+ * @def STA_HAL_SPI_ENABLE
+ * @brief Enable module.
+ *
+ * Requires **HAL_GPIO** module.
+ *
+ * @ingroup halBuildConfig
+ */
+#  define STA_HAL_SPI_ENABLE
+#endif // DOXYGEN
+
+
 #include <sta/config.hpp>
 #ifdef STA_HAL_SPI_ENABLE
 
 #ifndef STA_HAL_GPIO_ENABLE
-#error "HAL GPIO required"
+#error "HAL GPIO module required"
 #endif // !STA_HAL_GPIO_ENABLE
 
 #include <sta/hal.hpp>
@@ -24,6 +39,12 @@
 
 namespace sta
 {
+	/**
+	 * @ingroup halSPI
+	 * @{
+	 */
+
+
 	/**
 	 * @brief Get peripheral clock frequency.
 	 *
@@ -86,6 +107,9 @@ namespace sta
 	private:
 		HalGpioPin csPin_;  /**< Device CS pin */
 	};
+
+
+	/** @} */
 } // namespace sta
 
 
@@ -99,6 +123,8 @@ namespace sta
  * peripheral clock is used.
  *
  * @param handle    SPI interface handle
+ *
+ * @ingroup halSPI
  */
 #define STA_HAL_SPI_INFO(handle) sta::HalSpiInterfaceInfo{&handle, STA_HAL_GET_HANDLE_PCLK_FREQ_FN(handle)}
 

include/sta/hal/uart.hpp

@@ -1,13 +1,35 @@
 /**
+ * @file
  * @brief Implementation of UART using HAL.
- *
- * Configuration:
- *     STA_HAL_UART_ENABLE:         Enable module
- *     STA_HAL_UART_DEBUG_SERIAL:   Create global `sta::DebugSerial` object using this UART instance
  */
 #ifndef STA_HAL_UART_HPP
 #define STA_HAL_UART_HPP
 
+/**
+ * @defgroup halUART UART
+ * @ingroup hal
+ * @brief HAL UART module.
+ */
+
+#ifdef DOXYGEN
+/**
+ * @def STA_HAL_UART_ENABLE
+ * @brief Enable module.
+ *
+ * @ingroup halBuildConfig
+ */
+#  define STA_HAL_UART_ENABLE
+
+/**
+ * @def STA_HAL_UART_DEBUG_SERIAL
+ * @brief Create global sta::DebugSerial object using this HAL UART instance.
+ *
+ * @ingroup halBuildConfig
+ */
+#  define STA_HAL_UART_DEBUG_SERIAL
+#endif // DOXYGEN
+
+
 #include <sta/config.hpp>
 #ifdef STA_HAL_UART_ENABLE
 
@@ -18,7 +40,9 @@
 namespace sta
 {
 	/**
-	 * @brief Implementation of `UART` interface using HAL.
+	 * @brief Implementation of UART interface using HAL.
+	 *
+	 * @ingroup halUART
 	 */
 	class HalUART : public UART
 	{

include/sta/intf/uart.hpp

@@ -1,4 +1,5 @@
 /**
+ * @file
  * @brief UART interface definition.
  */
 #ifndef STA_INTF_UART_HPP
@@ -11,13 +12,13 @@
 namespace sta
 {
 	/**
-	 * @brief Interface for UART.
+	 * @brief Interface for %UART.
 	 */
 	class UART
 	{
 	public:
 		/**
-		 * @brief Write buffer to UART.
+		 * @brief Write buffer to %UART.
 		 *
 		 * @param buffer    Source buffer
 		 * @param size      Number of bytes in buffer
@@ -25,19 +26,19 @@ namespace sta
 		virtual void write(const uint8_t * buffer, size_t size) = 0;
 
 		/**
-		 * @brief Write unsigned integer to UART.
+		 * @brief Write unsigned integer to %UART.
 		 *
 		 * @param value     Unsigned integer value
 		 */
 		void write(uint8_t value);
 		/**
-		 * @brief Write unsigned integer to UART.
+		 * @brief Write unsigned integer to %UART.
 		 *
 		 * @param value     Unsigned integer value
 		 */
 		void write(uint16_t value);
 		/**
-		 * @brief Write unsigned integer to UART.
+		 * @brief Write unsigned integer to %UART.
 		 *
 		 * @param value     Unsigned integer value
 		 */

include/sta/printable_uart.hpp

@@ -1,5 +1,6 @@
 /**
- * @brief UART interface definition.
+ * @file
+ * @brief Printable UART interface definition.
  */
 #ifndef STA_PRINTABLE_UART_HPP
 #define STA_PRINTABLE_UART_HPP
@@ -23,11 +24,14 @@ namespace sta
 	};
 
 	/**
-	 * @brief Interface for UART.
+	 * @brief Printable interface for UART.
 	 */
 	class PrintableUART
 	{
 	public:
+		/**
+		 * @param intf  UART instance
+		 */
 		PrintableUART(UART * intf);
 
 		/**