Merge pull request 'Better/updated Doxygen support' (#21) from doxygen into main

Reviewed-on: https://git.intern.spaceteamaachen.de/ALPAKA/TACOS/pulls/21
Reviewed-by: dario <dario@noreply.git.intern.spaceteamaachen.de>

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

include/sta/tacos.hpp

@@ -15,6 +15,12 @@
 #include <initializer_list>
 #include <type_traits>
 
+/**
+ * @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<typename T, typename ... Args>
 		void addThread(std::list<uint16_t> states, Args ... args)

include/sta/tacos/manager.hpp

@@ -11,7 +11,7 @@
 
 #include <sta/config.hpp>
 
-#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()
 			{

include/sta/tacos/statemachine.hpp

@@ -10,25 +10,55 @@
 
 #include <sta/config.hpp>
 
-#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 <sta/tacos/thread.hpp>
 #include <sta/rtos/queue.hpp>
@@ -40,13 +70,6 @@
 #include <functional>
 #include <tuple>
 
-
-/**
- * @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; 		
 		};
 
 		/**

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;
 
 			/**

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()