From 6c76dfc7aed2594579f09d0b797d6a51cffff343 Mon Sep 17 00:00:00 2001 From: prozessorkern Date: Wed, 1 Apr 2020 19:16:11 +0200 Subject: [PATCH] fixed comments to get rid of doxygen warnings --- cfg/doxygen/doxyfile | 81 +++++++++++++++++++++++----------------- src/shellmatta.c | 6 +-- src/shellmatta_escape.c | 8 ++-- src/shellmatta_history.c | 17 ++++----- src/shellmatta_opt.c | 4 +- src/shellmatta_utils.c | 2 +- src/shellmatta_utils.h | 23 +++++++++++- 7 files changed, 85 insertions(+), 56 deletions(-) diff --git a/cfg/doxygen/doxyfile b/cfg/doxygen/doxyfile index 35ccd1d..7abfba6 100644 --- a/cfg/doxygen/doxyfile +++ b/cfg/doxygen/doxyfile @@ -1,4 +1,4 @@ -# Doxyfile 1.8.15 +# Doxyfile 1.8.17 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. @@ -197,6 +197,16 @@ SHORT_NAMES = NO JAVADOC_AUTOBRIEF = NO +# If the JAVADOC_BANNER tag is set to YES then doxygen will interpret a line +# such as +# /*************** +# as being the beginning of a Javadoc-style comment "banner". If set to NO, the +# Javadoc-style will behave just like regular comments and it will not be +# interpreted by doxygen. +# The default value is: NO. + +JAVADOC_BANNER = NO + # If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first # line (until the first dot) of a Qt-style comment as the brief description. If # set to NO, the Qt-style will behave just like regular Qt-style comments (thus @@ -299,7 +309,7 @@ OPTIMIZE_OUTPUT_SLICE = NO # parses. With this tag you can assign which parser to use for a given # extension. Doxygen has a built-in mapping, but you can override or extend it # using this tag. The format is ext=language, where ext is a file extension, and -# language is one of the parsers supported by doxygen: IDL, Java, Javascript, +# language is one of the parsers supported by doxygen: IDL, Java, JavaScript, # Csharp (C#), C, C++, D, PHP, md (Markdown), Objective-C, Python, Slice, # Fortran (fixed format Fortran: FortranFixed, free formatted Fortran: # FortranFree, unknown formatted Fortran: Fortran. In the later case the parser @@ -329,7 +339,7 @@ MARKDOWN_SUPPORT = YES # to that level are automatically included in the table of contents, even if # they do not have an id attribute. # Note: This feature currently applies only to Markdown headings. -# Minimum value: 0, maximum value: 99, default value: 0. +# Minimum value: 0, maximum value: 99, default value: 5. # This tag requires that the tag MARKDOWN_SUPPORT is set to YES. TOC_INCLUDE_HEADINGS = 0 @@ -465,6 +475,12 @@ EXTRACT_ALL = NO EXTRACT_PRIVATE = NO +# If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual +# methods of a class will be included in the documentation. +# The default value is: NO. + +EXTRACT_PRIV_VIRTUAL = NO + # If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal # scope will be included in the documentation. # The default value is: NO. @@ -519,8 +535,8 @@ HIDE_UNDOC_MEMBERS = NO HIDE_UNDOC_CLASSES = NO # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend -# (class|struct|union) declarations. If set to NO, these declarations will be -# included in the documentation. +# declarations. If set to NO, these declarations will be included in the +# documentation. # The default value is: NO. HIDE_FRIEND_COMPOUNDS = NO @@ -543,7 +559,7 @@ INTERNAL_DOCS = NO # names in lower-case letters. If set to YES, upper-case letters are also # allowed. This is useful if you have classes or files whose names only differ # in case and if your file system supports case sensitive file names. Windows -# and Mac users are advised to set this option to NO. +# (including Cygwin) ands Mac users are advised to set this option to NO. # The default value is: system dependent. CASE_SENSE_NAMES = YES @@ -813,7 +829,8 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = src api +INPUT = src \ + api # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -835,8 +852,10 @@ INPUT_ENCODING = UTF-8 # If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, # *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, # *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, -# *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, -# *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf, *.qsf and *.ice. +# *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C comment), +# *.doc (to be provided as doxygen C comment), *.txt (to be provided as doxygen +# C comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f, *.for, *.tcl, *.vhd, +# *.vhdl, *.ucf, *.qsf and *.ice. FILE_PATTERNS = *.c \ *.cc \ @@ -1250,9 +1269,9 @@ HTML_TIMESTAMP = NO # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML # documentation will contain a main index with vertical navigation menus that -# are dynamically created via Javascript. If disabled, the navigation index will +# are dynamically created via JavaScript. If disabled, the navigation index will # consists of multiple levels of tabs that are statically embedded in every HTML -# page. Disable this option to support browsers that do not have Javascript, +# page. Disable this option to support browsers that do not have JavaScript, # like the Qt help browser. # The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. @@ -1403,7 +1422,7 @@ QCH_FILE = # The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help # Project output. For more information please see Qt Help Project / Namespace -# (see: http://doc.qt.io/archives/qt-4.8/qthelpproject.html#namespace). +# (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#namespace). # The default value is: org.doxygen.Project. # This tag requires that the tag GENERATE_QHP is set to YES. @@ -1411,7 +1430,7 @@ QHP_NAMESPACE = org.doxygen.Project # The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt # Help Project output. For more information please see Qt Help Project / Virtual -# Folders (see: http://doc.qt.io/archives/qt-4.8/qthelpproject.html#virtual- +# Folders (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#virtual- # folders). # The default value is: doc. # This tag requires that the tag GENERATE_QHP is set to YES. @@ -1420,7 +1439,7 @@ QHP_VIRTUAL_FOLDER = doc # If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom # filter to add. For more information please see Qt Help Project / Custom -# Filters (see: http://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom- +# Filters (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom- # filters). # This tag requires that the tag GENERATE_QHP is set to YES. @@ -1428,7 +1447,7 @@ QHP_CUST_FILTER_NAME = # The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the # custom filter to add. For more information please see Qt Help Project / Custom -# Filters (see: http://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom- +# Filters (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom- # filters). # This tag requires that the tag GENERATE_QHP is set to YES. @@ -1436,7 +1455,7 @@ QHP_CUST_FILTER_ATTRS = # The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this # project's filter section matches. Qt Help Project / Filter Attributes (see: -# http://doc.qt.io/archives/qt-4.8/qthelpproject.html#filter-attributes). +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#filter-attributes). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_SECT_FILTER_ATTRS = @@ -1540,8 +1559,14 @@ FORMULA_FONTSIZE = 10 FORMULA_TRANSPARENT = YES +# The FORMULA_MACROFILE can contain LaTeX \newcommand and \renewcommand commands +# to create new LaTeX commands to be used in formulas as building blocks. See +# the section "Including formulas" for details. + +FORMULA_MACROFILE = + # Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see -# https://www.mathjax.org) which uses client side Javascript for the rendering +# https://www.mathjax.org) which uses client side JavaScript for the rendering # instead of using pre-rendered bitmaps. Use this if you do not have LaTeX # installed or if you want to formulas look prettier in the HTML output. When # enabled you may also need to install MathJax separately and configure the path @@ -1611,7 +1636,7 @@ MATHJAX_CODEFILE = SEARCHENGINE = YES # When the SERVER_BASED_SEARCH tag is enabled the search engine will be -# implemented using a web server instead of a web client using Javascript. There +# implemented using a web server instead of a web client using JavaScript. There # are two flavors of web server based searching depending on the EXTERNAL_SEARCH # setting. When disabled, doxygen will generate a PHP script for searching and # an index file used by the script. When EXTERNAL_SEARCH is enabled the indexing @@ -1715,10 +1740,11 @@ LATEX_CMD_NAME = MAKEINDEX_CMD_NAME = makeindex # The LATEX_MAKEINDEX_CMD tag can be used to specify the command name to -# generate index for LaTeX. +# generate index for LaTeX. In case there is no backslash (\) as first character +# it will be automatically added in the LaTeX code. # Note: This tag is used in the generated output file (.tex). # See also: MAKEINDEX_CMD_NAME for the part in the Makefile / make.bat. -# The default value is: \makeindex. +# The default value is: makeindex. # This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_MAKEINDEX_CMD = \makeindex @@ -2210,12 +2236,6 @@ EXTERNAL_GROUPS = YES EXTERNAL_PAGES = YES -# The PERL_PATH should be the absolute path and name of the perl script -# interpreter (i.e. the result of 'which perl'). -# The default file (with absolute path) is: /usr/bin/perl. - -PERL_PATH = /usr/bin/perl - #--------------------------------------------------------------------------- # Configuration options related to the dot tool #--------------------------------------------------------------------------- @@ -2229,15 +2249,6 @@ PERL_PATH = /usr/bin/perl CLASS_DIAGRAMS = YES -# You can define message sequence charts within doxygen comments using the \msc -# command. Doxygen will then run the mscgen tool (see: -# http://www.mcternan.me.uk/mscgen/)) to produce the chart and insert it in the -# documentation. The MSCGEN_PATH tag allows you to specify the directory where -# the mscgen tool resides. If left empty the tool is assumed to be found in the -# default search path. - -MSCGEN_PATH = - # You can include diagrams made with dia in doxygen documentation. Doxygen will # then run dia to produce the diagram and insert it in the documentation. The # DIA_PATH tag allows you to specify the directory where the dia binary resides. diff --git a/src/shellmatta.c b/src/shellmatta.c index 630221e..07965e0 100644 --- a/src/shellmatta.c +++ b/src/shellmatta.c @@ -327,7 +327,7 @@ shellmatta_retCode_t shellmatta_removeCmd(shellmatta_handle_t handle, shellmatta * @param[in] handle shellmatta instance handle * @param[in] mode insert mode of the shellmatta type #shellmatta_mode_t * @param[in] echoEnabled true: echo received chars to the output - * @param[in] delimiter delimiter used to detect the end of a cmd (default \r) + * @param[in] delimiter delimiter used to detect the end of a cmd (default "\r") * @return errorcode #SHELLMATTA_OK * #SHELLMATTA_USE_FAULT (param err) */ @@ -443,13 +443,13 @@ shellmatta_retCode_t shellmatta_processData(shellmatta_handle_t handle, if(0u == inst->hereLength) { /** - * \dot + * @dot * digraph heredocParser { * start -> wait [ label="<< in first line - store delimiter" ]; * wait -> wait [ label="delimiter not detected" ]; * wait -> end [ label="delimiter found - remove all heredoc stuff and send the input to the command" ]; * } - * \enddot */ + * @enddot */ /** -# check for heredoc - add string delimiter to stop strstr from searching too far */ inst->buffer[inst->inputCount] = '\0'; diff --git a/src/shellmatta_escape.c b/src/shellmatta_escape.c index 558a565..ed69210 100644 --- a/src/shellmatta_escape.c +++ b/src/shellmatta_escape.c @@ -44,11 +44,11 @@ shellmatta_retCode_t escape_processArrowKeys(shellmatta_instance_t *inst) history_storeCmd(inst); if(false == inst->historyReadUp) { - history_navigate(inst, -1); + (void)history_navigate(inst, -1); } inst->historyReadUp = true; history_restoreCmd(inst); - history_navigate(inst, -1); + (void)history_navigate(inst, -1); break; case 'B': /* arrow down */ @@ -58,10 +58,10 @@ shellmatta_retCode_t escape_processArrowKeys(shellmatta_instance_t *inst) history_storeCmd(inst); if(true == inst->historyReadUp) { - history_navigate(inst, 1); + (void)history_navigate(inst, 1); } inst->historyReadUp = false; - history_navigate(inst, 1); + (void)history_navigate(inst, 1); history_restoreCmd(inst); } break; diff --git a/src/shellmatta_history.c b/src/shellmatta_history.c index 1731dc2..a97d17e 100644 --- a/src/shellmatta_history.c +++ b/src/shellmatta_history.c @@ -59,7 +59,7 @@ static void appendHistoryByte(shellmatta_instance_t *inst, char byte) * @brief reads a byte from the history buffer and decreases the read index * @param[in] inst pointer to a shellmatta instance * @param[out] byte pointer to a char where the read out byte will be stored - * @return + * @return false: no new byte to read */ static bool getHistoryByte(shellmatta_instance_t *inst, char *byte) { @@ -84,6 +84,12 @@ static bool getHistoryByte(shellmatta_instance_t *inst, char *byte) return ret; } +/** + * @brief navigates in the history buffer by the given number of commands + * @param[in, out] inst pointer to a shellmatta instance + * @param[in] cnt direction and count to navigate + * @return false: end of buffer reached + */ bool history_navigate(shellmatta_instance_t *inst, int32_t cnt) { bool ret = true; @@ -185,13 +191,6 @@ void history_storeCmd(shellmatta_instance_t *inst) inst->dirty = false; } -/** - * @brief navigates in the history buffer by the given number of commands - * @param[in] inst pointer to a shellmatta instance - * @param[in] cnt direction and count to navigate - * @return - */ - /** * @brief restores the command from the history buffer where the read * index points on @@ -224,7 +223,7 @@ void history_restoreCmd(shellmatta_instance_t *inst) utils_writeEcho(inst, inst->buffer, inst->inputCount); inst->dirty = false; } - history_navigate(inst, 1); + (void)history_navigate(inst, 1); } /** diff --git a/src/shellmatta_opt.c b/src/shellmatta_opt.c index 5f740c9..19a7a90 100644 --- a/src/shellmatta_opt.c +++ b/src/shellmatta_opt.c @@ -116,7 +116,7 @@ static char peekNextHunk(shellmatta_instance_t *inst) /** * @brief tries to parse the current input hunk and check if this is a configured option - * @param[in] handle shellmatta handle + * @param[in] inst pointer to shellmatta instance * @param[in] optionString option string e.g. "cd:e::" * @param[out] option pointer to store the detected option to * @param[out] argtype pointer to var of type #shellmatta_opt_argtype_t != NULL @@ -178,7 +178,7 @@ static shellmatta_retCode_t parseShortOpt( shellmatta_instance_t *inst, /** * @brief tries to parse the current input hunk and check if this is a configured option - * @param[in] handle shellmatta handle + * @param[in] inst pointer to shellmatta instance * @param[in] longOptions option structure - pointer to array of type #shellmatta_opt_long_t * @param[out] option pointer to store the detected option to * @param[out] argtype pointer to var of type #shellmatta_opt_argtype_t != NULL diff --git a/src/shellmatta_utils.c b/src/shellmatta_utils.c index 14e4e0e..da18af6 100644 --- a/src/shellmatta_utils.c +++ b/src/shellmatta_utils.c @@ -294,7 +294,7 @@ static shellmatta_retCode_t helpCmdFct(shellmatta_handle_t handle, const char *a /** -# loop through all commands to determine the lengths of each cmd */ while(NULL != cmd) { - maxCmdLen = SHELLMATTA_MAX(maxCmdLen, strlen(cmd->cmd)); + maxCmdLen = SHELLMATTA_MAX(maxCmdLen, strlen(cmd->cmd)); if(NULL != cmd->cmdAlias) { maxCmdAliasLen = SHELLMATTA_MAX(maxCmdAliasLen, strlen(cmd->cmdAlias)); diff --git a/src/shellmatta_utils.h b/src/shellmatta_utils.h index ffa2351..ba52662 100644 --- a/src/shellmatta_utils.h +++ b/src/shellmatta_utils.h @@ -22,9 +22,26 @@ #include "shellmatta.h" #include -/* some helper macros */ +/** + * @brief returns the minimum of a and b + * @param[in] a parameter a + * @param[in] b parameter b + */ #define SHELLMATTA_MIN(a,b) (((a) > (b)) ? (b) : (a)) + +/** + * @brief returns the maximum of a and b + * @param[in] a parameter a + * @param[in] b parameter b + */ #define SHELLMATTA_MAX(a,b) (((a) < (b)) ? (b) : (a)) + +/** + * @brief calls fct with cnt bytes from buffer (to print cnt same bytes) + * @param[in] buffer buffer to send (shall contain the same char) + * @param[in] cnt count of bytes to send + * @param[in] fct write function + */ #define SHELLMATTA_PRINT_BUFFER(buffer,cnt,fct) \ while((cnt) > sizeof((buffer))) \ { \ @@ -36,11 +53,13 @@ (fct)((buffer), (cnt)); \ } +/** @brief help command which prints all shellmatta commands as table */ extern const shellmatta_cmd_t helpCmd; +/** @brief magic used to check if a shellmatta instance is initiated */ #define SHELLMATTA_MAGIC 0x5101E110u -/** \brief overwritable output buffer size */ +/** @brief overwritable output buffer size */ #ifndef SHELLMATTA_OUTPUT_BUFFER_SIZE #define SHELLMATTA_OUTPUT_BUFFER_SIZE 128u #endif