Add doxygen docs

include/sta/assert.hpp

@@ -1,23 +1,51 @@
 /**
+ * @file
  * @brief Assertion handling.
- *
- * 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
- *
- * 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.
- *
- * 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
 
+/**
+ * @defgroup staCore Core
+ * @brief STA Core library
+ */
+
+/**
+ * @defgroup staCoreBuildConfig Build Config
+ * @ingroup staCore
+ * @brief Build configuration options
+ */
+
+/**
+ * @defgroup staCoreAssert Assert
+ * @ingroup staCore
+ * @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
@@ -33,6 +61,12 @@
 #endif // NDEBUG || STA_ASSERT_DISABLE
 
 
+// Show enabled module in doxygen output
+#ifdef DOXYGEN
+#  define STA_ASSERT_ENABLE
+#endif // DOXYGEN
+
+
 #ifdef STA_ASSERT_ENABLE
 
 #include <cstdint>
@@ -43,19 +77,36 @@ namespace sta
 	/**
 	 * @brief Handle failed assertions.
 	 *
+	 * The default implementation uses **STA_DEBUG_PRINT** and will not
+	 * generate any output if the **DEBUG_SERIAL** module is disabled.
+	 *
+	 * Weak implementation can be overridden.
+	 *
 	 * @param expr  Asserted expression or message
 	 * @param file  File name
 	 * @param line  Line number
+	 *
+	 * @ingroup staCoreAssert
 	 */
 	void assert_failed(const char * expr, const char * file, uint32_t line);
+
 	/**
 	 * @brief Stop execution.
+	 *
+	 * Weak implementation can be overridden.
+	 *
+	 * @ingroup staCoreAssert
 	 */
 	void assert_halt();
 } // namespace sta
 
 
-// Use assert_halt if STA_HALT is not defined
+/**
+ * @def STA_HALT
+ * @brief Set function called after failed asserts.
+ *
+ * @ingroup staCoreBuildConfig
+ */
 #  ifndef STA_HALT
 #    define STA_HALT() sta::assert_halt()
 #  endif // !STA_HALT
@@ -65,62 +116,47 @@ namespace sta
  * @brief Assert expression.
  *
  * @param expr  Expression
+ *
+ * @ingroup staCoreAssert
  */
-#  define STA_ASSERT(expr)              ((void)(!(expr) && (sta::assert_failed(#expr, __FILE__, __LINE__), 1) && (STA_HALT(), 1)))
+#  define STA_ASSERT(expr)              ( (void)( !(expr) && ( sta::assert_failed(#expr, __FILE__, __LINE__), 1 ) && ( STA_HALT(), 1 ) ) )
 /**
  * @brief Assert expression.
  *
  * @param expr  Expression
  * @param msg   Message shown on failure
+ *
+ * @ingroup staCoreAssert
  */
-#  define STA_ASSERT_MSG(expr, msg)     ((void)(!(expr) && (sta::assert_failed(msg, __FILE__, __LINE__), 1) && (STA_HALT(), 1)))
+#  define STA_ASSERT_MSG(expr, msg)     ( (void)( !(expr) && ( sta::assert_failed(msg, __FILE__, __LINE__), 1 ) && ( STA_HALT(), 1 ) ) )
 /**
  * @brief Assert expression if condition is true.
  *
  * @param cond  Condition
  * @param expr  Expression
+ *
+ * @ingroup staCoreAssert
  */
-#  define STA_ASSERT_COND(cond, expr)   ((void)((cond) ? STA_ASSERT(expr) : 1))
+#  define STA_ASSERT_COND(cond, expr)   ( (void)( (cond) ? STA_ASSERT(expr) : 1 ) )
 /**
  * @brief Assert expression if condition is true.
  *
  * @param cond  Condition
  * @param expr  Expression
  * @param msg   Message shown on failure
+ *
+ * @ingroup staCoreAssert
  */
-#  define STA_ASSERT_COND_MSG(cond, expr, msg)  ((void)((cond) ? STA_ASSERT_MSG(expr, msg)))
+#  define STA_ASSERT_COND_MSG(cond, expr, msg)  ( (void)( (cond) ? STA_ASSERT_MSG(expr, msg) ) )
 
 #else // !STA_ASSERT_ENABLE
 
-/**
- * @brief Assert expression.
- *
- * @param expr  Expression
- */
-#  define STA_ASSERT(expr, msg)         ((void)0)
-/**
- * @brief Assert expression.
- *
- * @param expr  Expression
- * @param msg   Message shown on failure
- */
-#  define STA_ASSERT_MSG(expr, msg)     ((void)0)
-/**
- * @brief Assert expression if condition is true.
- *
- * @param cond  Condition
- * @param expr  Expression
- */
-#  define STA_ASSERT_COND(cond, expr)   ((void)0)
-/**
- * @brief Assert expression if condition is true.
- *
- * @param cond  Condition
- * @param expr  Expression
- * @param msg   Message shown on failure
- */
+#  define STA_ASSERT(expr)                      ((void)0)
+#  define STA_ASSERT_MSG(expr, msg)             ((void)0)
+#  define STA_ASSERT_COND(cond, expr)           ((void)0)
 #  define STA_ASSERT_COND_MSG(cond, expr, msg)  ((void)0)
 
 #endif // !STA_ASSERT_ENABLE
 
+
 #endif // STA_ASSERT_HPP