fixed comments to get rid of doxygen warnings

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
+# declarations. If set to NO, these declarations will be included in the
-# included in the documentation.
+# 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,
+# *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C comment),
-# *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf, *.qsf and *.ice.
+# *.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.

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';

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;

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

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

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

src/shellmatta_utils.h

@@ -22,9 +22,26 @@
 #include "shellmatta.h"
 #include <stdint.h>
 
-/* 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