Full Doxygen documentation

docs/Doxyfile

@@ -1,4 +1,4 @@
-# Doxyfile 1.9.4
+# Doxyfile 1.9.3
 
 # This file describes the settings to be used by the documentation system
 # doxygen (www.doxygen.org) for a project.
@@ -12,15 +12,6 @@
 # For lists, items can also be appended using:
 # TAG += value [value, ...]
 # Values that contain spaces should be placed between quotes (\" \").
-#
-# Note:
-#
-# Use doxygen to compare the used configuration file with the template
-# configuration file:
-# doxygen -x [configFile]
-# Use doxygen to compare the used configuration file with the template
-# configuration file without replacing the environment variables:
-# doxygen -x_noenv [configFile]
 
 #---------------------------------------------------------------------------
 # Project related configuration options
@@ -41,7 +32,7 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = "RTOS2"
+PROJECT_NAME           = RTOS2
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version
@@ -69,28 +60,16 @@ PROJECT_LOGO           =
 
 OUTPUT_DIRECTORY       = docs
 
-# If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096
+# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
-# sub-directories (in 2 levels) under the output directory of each output format
+# directories (in 2 levels) under the output directory of each output format and
-# and will distribute the generated files over these directories. Enabling this
+# will distribute the generated files over these directories. Enabling this
 # option can be useful when feeding doxygen a huge amount of source files, where
 # putting all generated files in the same directory would otherwise causes
-# performance problems for the file system. Adapt CREATE_SUBDIRS_LEVEL to
+# performance problems for the file system.
-# control the number of sub-directories.
 # The default value is: NO.
 
 CREATE_SUBDIRS         = NO
 
-# Controls the number of sub-directories that will be created when
-# CREATE_SUBDIRS tag is set to YES. Level 0 represents 16 directories, and every
-# level increment doubles the number of directories, resulting in 4096
-# directories at level 8 which is the default and also the maximum value. The
-# sub-directories are organized in 2 levels, the first level always has a fixed
-# numer of 16 directories.
-# Minimum value: 0, maximum value: 8, default value: 8.
-# This tag requires that the tag CREATE_SUBDIRS is set to YES.
-
-CREATE_SUBDIRS_LEVEL   = 8
-
 # If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII
 # characters to appear in the names of generated files. If set to NO, non-ASCII
 # characters will be escaped, for example _xE3_x81_x84 will be used for Unicode
@@ -102,14 +81,14 @@ ALLOW_UNICODE_NAMES    = NO
 # The OUTPUT_LANGUAGE tag is used to specify the language in which all
 # documentation generated by doxygen is written. Doxygen will use this
 # information to generate all constant output in the proper language.
-# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Bulgarian,
+# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese,
-# Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, Dutch, English
+# Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States),
-# (United States), Esperanto, Farsi (Persian), Finnish, French, German, Greek,
+# Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian,
-# Hindi, Hungarian, Indonesian, Italian, Japanese, Japanese-en (Japanese with
+# Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages),
-# English messages), Korean, Korean-en (Korean with English messages), Latvian,
+# Korean, Korean-en (Korean with English messages), Latvian, Lithuanian,
-# Lithuanian, Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese,
+# Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian,
-# Romanian, Russian, Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish,
+# Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish,
-# Swedish, Turkish, Ukrainian and Vietnamese.
+# Ukrainian and Vietnamese.
 # The default value is: English.
 
 OUTPUT_LANGUAGE        = English
@@ -481,7 +460,7 @@ TYPEDEF_HIDES_STRUCT   = NO
 
 LOOKUP_CACHE_SIZE      = 0
 
-# The NUM_PROC_THREADS specifies the number of threads doxygen is allowed to use
+# The NUM_PROC_THREADS specifies the number threads doxygen is allowed to use
 # during processing. When set to 0 doxygen will based this on the number of
 # cores available in the system. You can set it explicitly to a value larger
 # than 0 to get more control over the balance between CPU load and processing
@@ -606,7 +585,7 @@ INTERNAL_DOCS          = NO
 # filesystem is case sensitive (i.e. it supports files in the same directory
 # whose names only differ in casing), the option must be set to YES to properly
 # deal with such files in case they appear in the input. For filesystems that
-# are not case sensitive the option should be set to NO to properly deal with
+# are not case sensitive the option should be be set to NO to properly deal with
 # output files written for symbols that only differ in casing, such as for two
 # classes, one named CLASS and the other named Class, and to also support
 # references to files without having to specify the exact matching casing. On
@@ -880,21 +859,10 @@ WARN_AS_ERROR          = NO
 # and the warning text. Optionally the format may contain $version, which will
 # be replaced by the version of the file (if it could be obtained via
 # FILE_VERSION_FILTER)
-# See also: WARN_LINE_FORMAT
 # The default value is: $file:$line: $text.
 
 WARN_FORMAT            = "$file:$line: $text"
 
-# In the $text part of the WARN_FORMAT command it is possible that a reference
-# to a more specific place is given. To make it easier to jump to this place
-# (outside of doxygen) the user can define a custom "cut" / "paste" string.
-# Example:
-# WARN_LINE_FORMAT = "'vi $file +$line'"
-# See also: WARN_FORMAT
-# The default value is: at line $line of file $file.
-
-WARN_LINE_FORMAT       = "at line $line of file $file"
-
 # The WARN_LOGFILE tag can be used to specify a file to which warning and error
 # messages should be written. If left blank the output is written to standard
 # error (stderr). In case the file specified cannot be opened for writing the
@@ -952,7 +920,7 @@ FILE_PATTERNS          = *.c \
                          *.md \
                          *.dox \
                          *.py \
-                         *.pyw \
+                         *.pyw
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
@@ -967,7 +935,11 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = Core Drivers Middlewares Debug Release
+EXCLUDE                = Core \
+                         Drivers \
+                         Middlewares \
+                         Debug \
+                         Release
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -1164,46 +1136,6 @@ USE_HTAGS              = NO
 
 VERBATIM_HEADERS       = YES
 
-# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the
-# clang parser (see:
-# http://clang.llvm.org/) for more accurate parsing at the cost of reduced
-# performance. This can be particularly helpful with template rich C++ code for
-# which doxygen's built-in parser lacks the necessary type information.
-# Note: The availability of this option depends on whether or not doxygen was
-# generated with the -Duse_libclang=ON option for CMake.
-# The default value is: NO.
-
-CLANG_ASSISTED_PARSING = NO
-
-# If the CLANG_ASSISTED_PARSING tag is set to YES and the CLANG_ADD_INC_PATHS
-# tag is set to YES then doxygen will add the directory of each input to the
-# include path.
-# The default value is: YES.
-# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES.
-
-CLANG_ADD_INC_PATHS    = YES
-
-# If clang assisted parsing is enabled you can provide the compiler with command
-# line options that you would normally use when invoking the compiler. Note that
-# the include paths will already be set by doxygen for the files and directories
-# specified with INPUT and INCLUDE_PATH.
-# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES.
-
-CLANG_OPTIONS          =
-
-# If clang assisted parsing is enabled you can provide the clang parser with the
-# path to the directory containing a file called compile_commands.json. This
-# file is the compilation database (see:
-# http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html) containing the
-# options used when the source files were built. This is equivalent to
-# specifying the -p option to a clang tool, such as clang-check. These options
-# will then be passed to the parser. Any options specified with CLANG_OPTIONS
-# will be added as well.
-# Note: The availability of this option depends on whether or not doxygen was
-# generated with the -Duse_libclang=ON option for CMake.
-
-CLANG_DATABASE_PATH    =
-
 #---------------------------------------------------------------------------
 # Configuration options related to the alphabetical class index
 #---------------------------------------------------------------------------
@@ -1861,7 +1793,7 @@ EXTRA_SEARCH_MAPPINGS  =
 # If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
 # The default value is: YES.
 
-GENERATE_LATEX         = YES
+GENERATE_LATEX         = NO
 
 # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -1869,7 +1801,7 @@ GENERATE_LATEX         = YES
 # The default directory is: latex.
 # This tag requires that the tag GENERATE_LATEX is set to YES.
 
-LATEX_OUTPUT           = latex
+LATEX_OUTPUT           =
 
 # The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be
 # invoked.
@@ -2276,8 +2208,7 @@ SEARCH_INCLUDES        = YES
 
 # The INCLUDE_PATH tag can be used to specify one or more directories that
 # contain include files that are not input files but should be processed by the
-# preprocessor. Note that the INCLUDE_PATH is not recursive, so the setting of
+# preprocessor.
-# RECURSIVE has no effect here.
 # This tag requires that the tag SEARCH_INCLUDES is set to YES.
 
 INCLUDE_PATH           =
@@ -2389,7 +2320,7 @@ HIDE_UNDOC_RELATIONS   = YES
 # set to NO
 # The default value is: NO.
 
-HAVE_DOT               = YES
+HAVE_DOT               = NO
 
 # The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed
 # to run in parallel. When set to 0 doxygen will base this on the number of
@@ -2446,8 +2377,7 @@ CLASS_GRAPH            = YES
 COLLABORATION_GRAPH    = YES
 
 # If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for
-# groups, showing the direct groups dependencies. See also the chapter Grouping
+# groups, showing the direct groups dependencies.
-# in the manual.
 # The default value is: YES.
 # This tag requires that the tag HAVE_DOT is set to YES.
 

include/sta/rtos/event.hpp

@@ -9,12 +9,18 @@
 #include <cmsis_os2.h>
 #include <sta/event.hpp>
 
+/**
+ * @defgroup STA_RTOS_EVENT Event
+ * @ingroup STA_RTOS_API
+ * @brief CMSIS RTOS2 Event.
+ */
+
 namespace sta
 {
 	/**
 	 * @brief Implementation of Event using CMSIS RTOS2.
 	 *
-	 * @ingroup STA_RTOS_API
+	 * @ingroup STA_RTOS_EVENT
 	 */
 	class RtosEvent : public Event
 	{
@@ -22,9 +28,30 @@ namespace sta
 		RtosEvent();
         ~RtosEvent();
 
+		/**
+		 * @brief Set given flags for the event.
+		 */
 		void set(uint32_t flags) override;
+
+		/**
+		 * @brief Clear given flags for the event.
+		 */
 		void clear(uint32_t flags) override;
+
+		/**
+		 * @brief Get current flags for the event.
+		 * 
+		 * @return Current flags.
+		 */
 		uint32_t get() override;
+
+		/**
+		 * @brief Wait for any of the given flags to be set.
+		 * 
+		 * @param flags Flags to wait for.
+		 * @param timeout Timeout in milliseconds.
+		 * @return Event flags before clearing or error code if highest bit set.
+		 */
 		uint32_t wait(uint32_t flags, uint32_t timeout = osWaitForever) override;
 
 	private:

include/sta/rtos/handle.hpp

@@ -3,6 +3,11 @@
 
 #include <type_traits>
 
+/**
+ * @defgroup STA_RTOS_HANDLE Handle
+ * @ingroup STA_RTOS_API
+ * @brief Helper for managing access to RTOS handles.
+ */
 
 namespace sta
 {
@@ -11,7 +16,7 @@ namespace sta
 	 *
 	 * @tparam T    CMSIS RTOS2 handle type
 	 *
-	 * @ingroup STA_RTOS_API
+	 * @ingroup STA_RTOS_HANDLE
 	 */
 	template <typename T>
 	class RtosHandle
@@ -27,6 +32,7 @@ namespace sta
 		 */
 		struct Deferred
 		{
+			/// @brief Handle variable address type
 			handle_type * pointer;
 
 			/**

include/sta/rtos/mempool.hpp

@@ -9,6 +9,11 @@
 
 #include <cstdint>
 
+/**
+ * @defgroup STA_RTOS_MEMPOOL MemPool
+ * @ingroup STA_RTOS_API
+ * @brief RTOS Memory Pool.
+ */
 
 namespace sta
 {
@@ -17,7 +22,7 @@ namespace sta
 	 *
 	 * @tparam Message type
 	 *
-	 * @ingroup STA_RTOS_API
+	 * @ingroup STA_RTOS_MEMPOOL
 	 */
 	template <typename T>
 	class RtosMemPool

include/sta/rtos/mutex.hpp

@@ -9,13 +9,17 @@
 
 #include <cmsis_os2.h>
 
+/**
+ * @defgroup STA_RTOS_MUTEX Mutex
+ * @ingroup STA_RTOS_API
+ * @brief RTOS Mutexes.
+ */
 
 namespace sta
 {
 	/**
 	 * @brief Implementation of Mutex interface using CMSIS RTOS2.
-	 *
+	 * @ingroup STA_RTOS_MUTEX
-	 * @ingroup STA_RTOS_API
 	 */
 	class RtosMutex : public Mutex
 	{
@@ -32,7 +36,14 @@ namespace sta
 		 */
 		RtosMutex(const char* name);
 
+		/**
+		 * @brief Acquire the mutex.
+		 */
 		void acquire() override;
+
+		/**
+		 * @brief Release the mutex.
+		 */
 		void release() override;
 
 	private:

include/sta/rtos/queue.hpp

@@ -9,6 +9,11 @@
 
 #include <cstdint>
 
+/**
+ * @defgroup STA_RTOS_QUEUE Queue
+ * @ingroup STA_RTOS_API
+ * @brief RTOS Queue.
+ */
 
 namespace sta
 {
@@ -17,7 +22,7 @@ namespace sta
 	 *
 	 * @tparam Message type
 	 *
-	 * @ingroup STA_RTOS_API
+	 * @ingroup STA_RTOS_QUEUE
 	 */
 	template <typename T>
 	class RtosQueue

include/sta/rtos/sharedmem.hpp

@@ -9,6 +9,12 @@
 
 #include <cstdint>
 
+/**
+ * @defgroup STA_RTOS_SHAREDMEM SharedMem
+ * @ingroup STA_RTOS_API
+ * @brief RTOS Shared Memory.
+ */
+
 
 namespace sta
 {
@@ -16,8 +22,8 @@ namespace sta
 	 * @brief Interface object for using CMSIS RTOS2 MemPool for one variable.
 	 *
 	 * @tparam Message type
-	 *
+     * 
-	 * @ingroup STA_RTOS_API
+	 * @ingroup STA_RTOS_SHAREDMEM
 	 */
 	template <typename T>
 	class RtosSharedMem

include/sta/rtos/signal.hpp

@@ -9,13 +9,19 @@
 
 #include <cmsis_os2.h>
 
+/**
+ * @defgroup STA_RTOS_SIGNAL Signal
+ * @ingroup STA_RTOS_API
+ * @brief RTOS Signal.
+ */
 
 namespace sta
 {
 	/**
 	 * @brief Implementation of Signal interface using CMSIS RTOS2.
 	 *
-	 * @ingroup STA_RTOS_API
+	 * @ingroup STA_RTOS_SIGNAL
+	 * 
 	 */
 	class RtosSignal : public Signal
 	{
@@ -25,9 +31,28 @@ namespace sta
 		 */
 		RtosSignal(osSemaphoreId_t semaphore);
 
+		/**
+		 * @brief Notify the signal.
+		 */
 		void notify() override;
+
+		/**
+		 * @brief Check if the signal is set.
+		 *
+		 * @return true if the signal is set.
+		 */
 		bool peek() override;
+
+		/**
+		 * @brief Check if the signal is set and clear it.
+		 *
+		 * @return true if the signal was set.
+		 */
 		bool test() override;
+
+		/**
+		 * @brief Wait for the signal to be set.
+		 */
 		void wait() override;
 
 	private:

include/sta/rtos/thread.hpp

@@ -7,7 +7,13 @@
 #include <cmsis_os2.h>
 
 /**
+ * @defgroup STA_RTOS_THREAD Thread
  * @ingroup STA_RTOS_API
+ * @brief RTOS Thread.
+ */
+
+/**
+ * @ingroup STA_RTOS_THREAD
  * @{
  */
 
@@ -43,11 +49,14 @@
 #define STA_RTOS_THREAD_FLAGS_ERROR_CODE_BITS       UINT32_C( 0x0000000F )
 #define STA_RTOS_THREAD_FLAGS_ERROR_CODE_EXT_BITS   UINT32_C( 0x7FFFFFF0 )
 
-
+/**
+ * @brief Error code from flags.
+ */
 #define STA_RTOS_THREAD_FLAGS_GET_EXT_ERROR_CODE(flags) (~flags & STA_RTOS_THREAD_FLAGS_ERROR_CODE_EXT_BITS)
 
-
+/**
-
+ * @brief Wait for any of the given flags to be set.
+ */
 #define STA_RTOS_THREAD_FLAGS_WAIT_ANY(timeout) osThreadFlagsWait(STA_RTOS_THREAD_FLAGS_VALID_BITS, osFlagsWaitAny, timeout)
 
 
@@ -59,7 +68,7 @@ namespace sta
 	/**
 	 * @brief Wrapper for RTOS thread control.
 	 *
-	 * @ingroup STA_RTOS_API
+	 * @ingroup STA_RTOS_THREAD
 	 */
 	class RtosThread
 	{

include/sta/rtos/timer.hpp

@@ -18,6 +18,8 @@ namespace sta
 	 * @brief Implementation of Timer using CMSIS RTOS2.
 	 *
 	 * @ingroup STA_RTOS_API
+	 * 
+	 * @defgroup STA_RTOS_TIMER Timer
 	 */
 	class RtosTimer : public Timer
 	{