From 4357b27ae45ec2ee3614775f23fdea1af0e1019a Mon Sep 17 00:00:00 2001 From: "@CarlWachter" Date: Sat, 6 Jan 2024 13:02:54 +0100 Subject: [PATCH] Improved grouping and allow doxygen without other defines --- docs/Doxyfile | 2 +- include/sta/tacos/manager.hpp | 4 ++- include/sta/tacos/statemachine.hpp | 55 ++++++++++++++++++++++-------- include/sta/tacos/thread.hpp | 7 ++++ src/startup.cpp | 16 +++++++-- 5 files changed, 66 insertions(+), 18 deletions(-) diff --git a/docs/Doxyfile b/docs/Doxyfile index 84bba31..46e1de7 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -38,7 +38,7 @@ PROJECT_NAME = TACOS # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 1.0.0 +PROJECT_NUMBER = 1.3.0 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a diff --git a/include/sta/tacos/manager.hpp b/include/sta/tacos/manager.hpp index bb300b1..e9e7120 100644 --- a/include/sta/tacos/manager.hpp +++ b/include/sta/tacos/manager.hpp @@ -11,7 +11,7 @@ #include -#ifndef STA_TACOS_MANAGER_PRIORITY +#if !defined(STA_TACOS_MANAGER_PRIORITY) && !defined(DOXYGEN) # error "Manger task priority not specified in config.hpp" #else @@ -40,6 +40,8 @@ namespace sta public: /** * @brief Get the singleton instance of the manager. + * + * @ingroup tacos_manager */ static Manager* instance() { diff --git a/include/sta/tacos/statemachine.hpp b/include/sta/tacos/statemachine.hpp index c901232..030e903 100644 --- a/include/sta/tacos/statemachine.hpp +++ b/include/sta/tacos/statemachine.hpp @@ -10,25 +10,55 @@ #include -#ifndef STA_TACOS_NUM_STATES +#if !defined(STA_TACOS_NUM_STATES) && !defined(DOXYGEN) # error "Number of states wasn't defined in config.hpp" #else - -#ifndef STA_TACOS_INITIAL_STATE +#if !defined(STA_TACOS_INITIAL_STATE) && !defined(DOXYGEN) # define STA_TACOS_INITIAL_STATE 0 #endif +/** + * @defgroup tacos_statemachine Statemachine Task + * @ingroup tacos + * @brief Statemachine task for TACOS. + */ +/** + * @brief The maximum number of state transitions that can be queued. + * + * @ingroup tacos_statemachine + */ #define STA_TACOS_STATEMACHINE_QUEUE_LENGTH 4 +/** + * @ingroup tacos_statemachine + * @{ + */ + // State transition happened because of +/** + * @brief State change due to requested Transition. +*/ #define STA_TACOS_STATE_CHANGE_NORMAL_FLAG ( 0x1U ) +/** + * @brief State change due to forced Transition. +*/ #define STA_TACOS_STATE_CHANGE_FORCED_FLAG ( 0x1U << 1) +/** + * @brief State change due to timeout. +*/ #define STA_TACOS_STATE_CHANGE_TIMEOUT ( 0x1U << 2) +/** + * @brief State change due to startup. +*/ #define STA_TACOS_STATE_CHANGE_STARTUP_FLAG ( 0x1U << 3) +/** + * @brief State change due to any reason. +*/ #define STA_TACOS_STATE_CHANGE_ALL_FLAG ( 0x15U ) +/** @} */ #include #include @@ -40,13 +70,6 @@ #include #include - -/** - * @defgroup tacos_statemachine Statemachine Task - * @ingroup tacos - * @brief Statemachine task for TACOS. - */ - namespace sta { namespace tacos @@ -72,10 +95,14 @@ namespace sta */ struct StateTransition { - uint16_t from; - uint16_t to; - EventFlags event; - uint32_t lockout; + /// Origin of transition + uint16_t from; + /// Destination of transition + uint16_t to; + /// Event that triggered the transition + EventFlags event; + /// Lockout time after transition + uint32_t lockout; }; /** diff --git a/include/sta/tacos/thread.hpp b/include/sta/tacos/thread.hpp index 989d081..ca01469 100644 --- a/include/sta/tacos/thread.hpp +++ b/include/sta/tacos/thread.hpp @@ -61,7 +61,14 @@ namespace sta */ const char* getName() const; + /** + * @brief Compare two threads by their names. + */ bool operator==(const TacosThread& other) const; + + /** + * @brief Compare two threads by their names. + */ bool operator<(const TacosThread& other) const; /** diff --git a/src/startup.cpp b/src/startup.cpp index 6550cc1..98448ed 100644 --- a/src/startup.cpp +++ b/src/startup.cpp @@ -6,8 +6,10 @@ */ /** - * @defgroup tacos - * @brief TACOS library. + * @defgroup tacos TACOS Library + * @brief TACOS library + * + * @details This library contains the internal functions of TACOS. It is not intended to be used by the user, but is documented rather for anyone wanting to contribute to the project. */ @@ -31,6 +33,12 @@ // The UART mutex defined in freertos.c extern osMutexId_t uartMutexHandle; +/** + * @defgroup tacos_startup Startup + * @ingroup tacos + * @brief Functions that are called during startup. + */ + namespace sta { @@ -60,6 +68,8 @@ namespace sta /** * @brief Function that is called before the statemachine task is started. Override it to * adjust the statemachine to your specifications. + * + * @ingroup tacos_startup */ STA_WEAK void onStatemachineInit() @@ -75,6 +85,8 @@ namespace sta /** * @brief Function that is called before the manager task is started. Override it to adjust * the manager to your specifications. + * + * @ingroup tacos_startup */ STA_WEAK void onManagerInit()