From b4b214a756b7c4cd138222d3a97bedd3fad1c35c Mon Sep 17 00:00:00 2001 From: "@CarlWachter" Date: Sat, 6 Jan 2024 16:30:30 +0100 Subject: [PATCH] Full Doxygen documentation --- docs/Doxyfile | 126 ++++++++------------------------- include/sta/rtos/event.hpp | 29 +++++++- include/sta/rtos/handle.hpp | 8 ++- include/sta/rtos/mempool.hpp | 7 +- include/sta/rtos/mutex.hpp | 15 +++- include/sta/rtos/queue.hpp | 7 +- include/sta/rtos/sharedmem.hpp | 10 ++- include/sta/rtos/signal.hpp | 27 ++++++- include/sta/rtos/thread.hpp | 17 +++-- include/sta/rtos/timer.hpp | 2 + 10 files changed, 137 insertions(+), 111 deletions(-) diff --git a/docs/Doxyfile b/docs/Doxyfile index f3fcdee..d4adfe2 100644 --- a/docs/Doxyfile +++ b/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 -# sub-directories (in 2 levels) under the output directory of each output format -# and will distribute the generated files over these directories. Enabling this +# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- +# directories (in 2 levels) under the output directory of each output format and +# 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 -# control the number of sub-directories. +# performance problems for the file system. # 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, -# Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, Dutch, English -# (United States), Esperanto, Farsi (Persian), Finnish, French, German, Greek, -# Hindi, Hungarian, Indonesian, Italian, Japanese, Japanese-en (Japanese with -# English messages), Korean, Korean-en (Korean with English messages), Latvian, -# Lithuanian, Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, -# Romanian, Russian, Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, -# Swedish, Turkish, Ukrainian and Vietnamese. +# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese, +# Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States), +# Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian, +# Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages), +# Korean, Korean-en (Korean with English messages), Latvian, Lithuanian, +# Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian, +# Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish, +# Ukrainian and Vietnamese. # The default value is: English. OUTPUT_LANGUAGE = English @@ -349,7 +328,7 @@ OPTIMIZE_OUTPUT_SLICE = NO # # Note see also the list of default file extension mappings. -EXTENSION_MAPPING = +EXTENSION_MAPPING = # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments # according to the Markdown format, which allows for more readable @@ -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 -# RECURSIVE has no effect here. +# preprocessor. # 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 -# in the manual. +# groups, showing the direct groups dependencies. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. diff --git a/include/sta/rtos/event.hpp b/include/sta/rtos/event.hpp index 95d1c89..8d9de03 100644 --- a/include/sta/rtos/event.hpp +++ b/include/sta/rtos/event.hpp @@ -9,12 +9,18 @@ #include #include +/** + * @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: diff --git a/include/sta/rtos/handle.hpp b/include/sta/rtos/handle.hpp index 2b92e8e..717466b 100644 --- a/include/sta/rtos/handle.hpp +++ b/include/sta/rtos/handle.hpp @@ -3,6 +3,11 @@ #include +/** + * @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 class RtosHandle @@ -27,6 +32,7 @@ namespace sta */ struct Deferred { + /// @brief Handle variable address type handle_type * pointer; /** diff --git a/include/sta/rtos/mempool.hpp b/include/sta/rtos/mempool.hpp index 1baa1e0..693af70 100644 --- a/include/sta/rtos/mempool.hpp +++ b/include/sta/rtos/mempool.hpp @@ -9,6 +9,11 @@ #include +/** + * @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 class RtosMemPool diff --git a/include/sta/rtos/mutex.hpp b/include/sta/rtos/mutex.hpp index 263ff0d..ff05415 100644 --- a/include/sta/rtos/mutex.hpp +++ b/include/sta/rtos/mutex.hpp @@ -9,13 +9,17 @@ #include +/** + * @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_API + * @ingroup STA_RTOS_MUTEX */ 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: diff --git a/include/sta/rtos/queue.hpp b/include/sta/rtos/queue.hpp index 3fb127e..3721646 100644 --- a/include/sta/rtos/queue.hpp +++ b/include/sta/rtos/queue.hpp @@ -9,6 +9,11 @@ #include +/** + * @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 class RtosQueue diff --git a/include/sta/rtos/sharedmem.hpp b/include/sta/rtos/sharedmem.hpp index d39141d..9e057cd 100644 --- a/include/sta/rtos/sharedmem.hpp +++ b/include/sta/rtos/sharedmem.hpp @@ -9,6 +9,12 @@ #include +/** + * @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 class RtosSharedMem diff --git a/include/sta/rtos/signal.hpp b/include/sta/rtos/signal.hpp index 1c9625f..39d6a5c 100644 --- a/include/sta/rtos/signal.hpp +++ b/include/sta/rtos/signal.hpp @@ -9,13 +9,19 @@ #include +/** + * @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: diff --git a/include/sta/rtos/thread.hpp b/include/sta/rtos/thread.hpp index 8aeffa4..98af9ef 100644 --- a/include/sta/rtos/thread.hpp +++ b/include/sta/rtos/thread.hpp @@ -7,7 +7,13 @@ #include /** + * @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 { diff --git a/include/sta/rtos/timer.hpp b/include/sta/rtos/timer.hpp index ac6714f..6447772 100644 --- a/include/sta/rtos/timer.hpp +++ b/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 {