fixed and enabled -Wdocumentation and -Wdocumentation-pedantic clang warnings (#2819)

cli/cppcheckexecutor.h

@@ -94,7 +94,7 @@ public:
     static void reportStatus(std::size_t fileindex, std::size_t filecount, std::size_t sizedone, std::size_t sizetotal);
 
     /**
-     * @param exception_output Output file
+     * @param exceptionOutput Output file
      */
     static void setExceptionOutput(FILE* exceptionOutput);
     /**

cmake/compileroptions.cmake

@@ -48,6 +48,9 @@ elseif (CMAKE_CXX_COMPILER_ID MATCHES "Clang")
    add_compile_options(-Wno-unused-function)
    add_compile_options_safe(-Wextra-semi-stmt)
    add_compile_options_safe(-Wcomma)
+   add_compile_options_safe(-Wdocumentation)
+   add_compile_options_safe(-Wdocumentation-pedantic)
+   add_compile_options_safe(-Wno-documentation-unknown-command)
 
    if(ENABLE_COVERAGE OR ENABLE_COVERAGE_XML)
       message(FATAL_ERROR "Do not use clang for generate code coverage. Use gcc.")

lib/checkleakautovar.cpp

@@ -55,7 +55,7 @@ static const int NEW = -1;
 
 /**
  * @brief Is variable type some class with automatic deallocation?
- * @param vartok variable token
+ * @param var variable token
  * @return true unless it can be seen there is no automatic deallocation
  */
 static bool isAutoDealloc(const Variable *var)

lib/path.h

@@ -175,7 +175,7 @@ public:
 
     /**
       * @brief Checks if a File exists
-      * @param path Path to be checked if it is a File
+      * @param file Path to be checked if it is a File
       * @return true if given path is a File
       */
     static bool fileExists(const std::string &file);

lib/templatesimplifier.h

@@ -140,16 +140,16 @@ public:
     public:
         /**
          * Constructor used for instantiations.
-         * \param tok template instantiation name token "name<...>"
+         * \param token template instantiation name token "name<...>"
-         * \param s full qualification of template(scope)
+         * \param scope full qualification of template(scope)
          */
         TokenAndName(Token *token, const std::string &scope);
         /**
          * Constructor used for declarations.
-         * \param tok template declaration token "template < ... >"
+         * \param token template declaration token "template < ... >"
-         * \param s full qualification of template(scope)
+         * \param scope full qualification of template(scope)
-         * \param nt template name token "template < ... > class name"
+         * \param nameToken template name token "template < ... > class name"
-         * \param pe template parameter end token ">"
+         * \param paramEnd template parameter end token ">"
          */
         TokenAndName(Token *token, const std::string &scope, const Token *nameToken, const Token *paramEnd);
         TokenAndName(const TokenAndName& other);

lib/token.h

@@ -342,7 +342,7 @@ public:
      * @param tok token with C-string
      * @param settings Settings
      **/
-    static nonneg int getStrSize(const Token *tok, const Settings *const);
+    static nonneg int getStrSize(const Token *tok, const Settings *const settings);
 
     /**
      * @return char of C-string at index (possible escaped "\\n")
@@ -887,19 +887,24 @@ public:
         }
     };
 
+	void stringify(std::ostream& os, const stringifyOptions& options) const;
+
     /**
      * Stringify a token
      * @param os The result is shifted into that output stream
-     * @param varid Print varids. (Style: "varname@id")
+     * @param varid Print varids. (Style: "varname\@id")
      * @param attributes Print attributes of tokens like "unsigned" in front of it.
      * @param macro Prints $ in front of the token if it was expanded from a macro.
      */
-    void stringify(std::ostream& os, const stringifyOptions& options) const;
     void stringify(std::ostream& os, bool varid, bool attributes, bool macro) const;
 
+	std::string stringifyList(const stringifyOptions& options, const std::vector<std::string>* fileNames = nullptr, const Token* end = nullptr) const;
+	std::string stringifyList(const Token* end, bool attributes = true) const;
+	std::string stringifyList(bool varid = false) const;
+
     /**
      * Stringify a list of token, from current instance on.
-     * @param varid Print varids. (Style: "varname@id")
+     * @param varid Print varids. (Style: "varname\@id")
      * @param attributes Print attributes of tokens like "unsigned" in front of it.
      * @param linenumbers Print line number in front of each line
      * @param linebreaks Insert "\\n" into string when line number changes
@@ -908,10 +913,7 @@ public:
      * @param end Stringification ends before this token is reached. 0 to stringify until end of list.
      * @return Stringified token list as a string
      */
-    std::string stringifyList(const stringifyOptions& options, const std::vector<std::string>* fileNames = nullptr, const Token* end = nullptr) const;
     std::string stringifyList(bool varid, bool attributes, bool linenumbers, bool linebreaks, bool files, const std::vector<std::string>* fileNames = nullptr, const Token* end = nullptr) const;
-    std::string stringifyList(const Token* end, bool attributes = true) const;
-    std::string stringifyList(bool varid = false) const;
 
     /**
      * Remove the contents for this token from the token list.