From 759495f2ceca200bfa691588d0ba906cfd577dc2 Mon Sep 17 00:00:00 2001 From: "@CarlWachter" Date: Sat, 6 Jan 2024 13:02:18 +0100 Subject: [PATCH 1/2] Added API group --- include/sta/tacos.hpp | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/include/sta/tacos.hpp b/include/sta/tacos.hpp index bec1616..3ca9f85 100644 --- a/include/sta/tacos.hpp +++ b/include/sta/tacos.hpp @@ -15,6 +15,12 @@ #include #include +/** + * @defgroup tacos_api TACOS API + * @brief Functions and classes that are used to interact with TACOS. + * + * @details This module contains all functions and classes that are used to interact with TACOS. It is the only module that should be used in user code. + */ namespace sta { @@ -24,6 +30,8 @@ namespace sta * @brief Get the current state of the TACOS statemachine. * * @return uint16_t Returns the state. + * + * @ingroup tacos_api */ uint16_t getState(); @@ -33,6 +41,8 @@ namespace sta * @param from The start we want to transition from. * @param to The state we want to transition to. * @param lockout An optional timer blocking state transition for a given time. + * + * @ingroup tacos_api */ void setState(uint32_t from, uint32_t to, uint32_t lockout = 0); @@ -43,6 +53,8 @@ namespace sta * @param to The state we want to transition to. * @param millis The time to wait until the transition is requested. * @param lockout An optional timer blocking state transition for a given time. Will be active after this transition was executed. + * + * @ingroup tacos_api */ void setStateTimed(uint32_t from, uint32_t to, uint32_t millis, uint32_t lockout = 0); @@ -52,6 +64,8 @@ namespace sta * @tparam T The class of the thread to be created. A subclass of TacosThread. * @param states A list of states in which the thread should run. * @param args The constructor arguments for the provided class. + * + * @ingroup tacos_api */ template void addThread(std::list states, Args ... args) From 4357b27ae45ec2ee3614775f23fdea1af0e1019a Mon Sep 17 00:00:00 2001 From: "@CarlWachter" Date: Sat, 6 Jan 2024 13:02:54 +0100 Subject: [PATCH 2/2] 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()