doxygen: updated comments for Cppcheck and FileLister

lib/cppcheck.h

@@ -32,7 +32,7 @@
 /// @{
 
 /**
- * This is the base class which will use other classes to do
+ * @brief This is the base class which will use other classes to do
  * static code analysis for C and C++ code to find possible
  * errors or places that could be improved.
  * Usage: See check() for more info.
@@ -41,24 +41,24 @@ class CppCheck : public ErrorLogger
 {
 public:
     /**
-     * Constructor.
+     * @brief Constructor.
      */
     CppCheck(ErrorLogger &errorLogger);
 
     /**
-     * Destructor.
+     * @brief Destructor.
      */
     virtual ~CppCheck();
 
     /**
-     * This starts the actual checking. Note that you must call
+     * @brief This starts the actual checking. Note that you must call
      * parseFromArgs() or settings() and addFile() before calling this.
      * @return amount of errors found or 0 if none were found.
      */
     unsigned int check();
 
     /**
-     * Adjust the settings before doing the check. E.g. show only
+     * @brief Adjust the settings before doing the check. E.g. show only
      * actual bugs or also coding style issues.
      *
      * @param settings New settings which will overwrite the old.
@@ -66,13 +66,13 @@ public:
     void settings(const Settings &settings);
 
     /**
-     * Get copy of current settings.
+     * @brief Get copy of current settings.
      * @return a copy of current settings
      */
     Settings settings() const;
 
     /**
-     * Add new file to be checked.
+     * @brief Add new file to be checked.
      *
      * @param path Relative or absolute path to the file to be checked,
      * e.g. "cppcheck.cpp". Note that only source files (.c, .cc or .cpp)
@@ -83,7 +83,7 @@ public:
     void addFile(const std::string &path);
 
     /**
-     * Add new unreal file to be checked.
+     * @brief Add new unreal file to be checked.
      *
      * @param path File name (used for error reporting).
      * @param content If the file would be a real file, this should be
@@ -92,12 +92,12 @@ public:
     void addFile(const std::string &path, const std::string &content);
 
     /**
-     * Remove all files added with addFile() and parseFromArgs().
+     * @brief Remove all files added with addFile() and parseFromArgs().
      */
     void clearFiles();
 
     /**
-     * Parse command line args and get settings and file lists
+     * @brief Parse command line args and get settings and file lists
      * from there.
      *
      * @param argc argc from main()
@@ -107,7 +107,7 @@ public:
     void parseFromArgs(int argc, const char* const argv[]);
 
     /**
-     * Returns current version number as a string.
+     * @brief Returns current version number as a string.
      * @return version, e.g. "1.38"
      */
     static const char * version();
@@ -117,7 +117,7 @@ public:
     virtual void reportStatus(unsigned int index, unsigned int max);
 
     /**
-     * Terminate checking. The checking will be terminated ASAP.
+     * @brief Terminate checking. The checking will be terminated as soon as possible.
      */
     void terminate()
     {
@@ -128,7 +128,7 @@ private:
     void checkFile(const std::string &code, const char FileName[]);
 
     /**
-     * Errors and warnings are directed here.
+     * @brief Errors and warnings are directed here.
      *
      * @param msg Errors messages are normally in format
      * "[filepath:line number] Message", e.g.
@@ -137,7 +137,7 @@ private:
     virtual void reportErr(const ErrorLogger::ErrorMessage &msg);
 
     /**
-     * Information about progress is directed here.
+     * @brief Information about progress is directed here.
      *
      * @param outmsg Message to show, e.g. "Checking main.cpp..."
      */
@@ -148,12 +148,14 @@ private:
     std::ostringstream _errout;
     Settings _settings;
     std::vector<std::string> _filenames;
-    /** Key is file name, and value is the content of the file */
+
+    /** @brief Key is file name, and value is the content of the file */
     std::map<std::string, std::string> _fileContents;
+
     CheckUnusedFunctions _checkUnusedFunctions;
     ErrorLogger &_errorLogger;
 
-    /** Current configuration */
+    /** @brief Current preprocessor configuration */
     std::string     cfg;
 
     std::list<std::string> _xmllist;

lib/filelister.h

@@ -25,18 +25,43 @@
 /// @addtogroup Core
 /// @{
 
-
+/** @brief Base class for Cppcheck filelisters. Used to recursively search for source files. This class defines a platform independant interface and subclasses will provide platform dependant implementation. */
 class FileLister
 {
 public:
+    /**
+     * @brief Add source files to a vector (*.c;*.cpp;*.cxx;*.c++;*.cc;*.txx)
+     * @param filenames output vector that filenames are written to
+     * @param path root path
+     * @param recursive Should files be added recursively or not?
+     */
     virtual void recursiveAddFiles(std::vector<std::string> &filenames, const std::string &path, bool recursive) = 0;
+
+    /**
+     * @brief simplify path "foo/bar/.." => "foo"
+     * @param originalPath path to be simplified
+     * @return simplified path
+     */
     virtual std::string simplifyPath(const char *originalPath);
+
+    /**
+     * @brief compare filenames to see if they are the same. On Linux the comparison is case-sensitive. On Windows it is case-insensitive.
+     * @param fname1 one filename
+     * @param fname2 other filename
+     * @return true if the filenames match on the current platform
+     */
     virtual bool sameFileName(const std::string &fname1, const std::string &fname2) = 0;
+
+    /**
+     * @brief check if the file extension indicates that it's a source file - *.c;*.cpp;*.cxx;*.c++;*.cc;*.txx
+     * @param filename filename
+     * @return returns true if the file extension indicates it should be checked
+     */
     virtual bool acceptFile(const std::string &filename);
-private:
 
 };
 
+/** @brief get filelister (platform dependent implementation) */
 FileLister * getFileLister();
 
 /// @}

lib/settings.h

@@ -30,118 +30,129 @@
 
 
 /**
- * This is just a container for general settings so that we don't need
+ * @brief This is just a container for general settings so that we don't need
  * to pass individual values to functions or constructors now or in the
  * future when we might have even more detailed settings.
  */
 class Settings
 {
 private:
-    /** classes that are automaticly deallocated */
+    /** @brief classes that are automaticly deallocated */
     std::set<std::string> _autoDealloc;
 
-    /** Code to append in the checks */
+    /** @brief Code to append in the checks */
     std::string _append;
 
-    /** enable extra checks by id */
+    /** @brief enable extra checks by id */
     std::map<std::string, bool> _enabled;
 
-    /** terminate checking */
+    /** @brief terminate checking */
     bool _terminate;
 public:
     Settings();
     virtual ~Settings();
 
+    /** @brief Is --debug given? */
     bool _debug;
+
+    /** @brief Is --all given? */
     bool _showAll;
+
+    /** @brief Is --style given? */
     bool _checkCodingStyle;
+
+    /** @brief Is --quiet given? */
     bool _errorsOnly;
+
+    /** @brief Is --inline-suppr given? */
     bool _inlineSuppressions;
+
+    /** @brief Is --verbose given? */
     bool _verbose;
 
-    /** Request termination of checking */
+    /** @brief Request termination of checking */
     void terminate()
     {
         _terminate = true;
     }
 
-    /** termination? */
+    /** @brief termination requested? */
     bool terminated() const
     {
         return _terminate;
     }
 
-    /** Force checking t he files with "too many" configurations. */
+    /** @brief Force checking the files with "too many" configurations (--force). */
     bool _force;
 
-    /** write xml results */
+    /** @brief write xml results (--xml) */
     bool _xml;
 
-    /** How many processes/threads should do checking at the same
+    /** @brief How many processes/threads should do checking at the same
-        time. Default is 1. */
+        time. Default is 1. (-j N) */
     unsigned int _jobs;
 
-    /** If errors are found, this value is returned from main().
+    /** @brief If errors are found, this value is returned from main().
         Default value is 0. */
     int _exitCode;
 
-    /** The output format in which the errors are printed in text mode,
+    /** @brief The output format in which the errors are printed in text mode,
         e.g. "{severity} {file}:{line} {message} {id}" */
     std::string _outputFormat;
 
-    /** show timing information */
+    /** @brief show timing information (--showtime) */
     bool _showtime;
 
-    /** List of include paths, e.g. "my/includes/" which should be used
+    /** @brief List of include paths, e.g. "my/includes/" which should be used
-        for finding include files inside source files. */
+        for finding include files inside source files. (-I) */
     std::list<std::string> _includePaths;
 
-    /** Fill list of automaticly deallocated classes */
+    /** @brief Fill list of automaticly deallocated classes (--auto-dealloc) */
     void autoDealloc(std::istream &istr);
 
-    /** Add class to list of automatically deallocated classes */
+    /** @brief Add class to list of automatically deallocated classes */
     void addAutoAllocClass(const std::string &name);
 
-    /** is a class automaticly deallocated? */
+    /** @brief is a class automaticly deallocated? */
     bool isAutoDealloc(const std::string &classname) const;
 
-    /** assign append code */
+    /** @brief assign append code (--append) */
     void append(const std::string &filename);
 
-    /** get append code */
+    /** @brief get append code (--append) */
     std::string append() const;
 
     /**
-     * Returns true if given id is in the list of
+     * @brief Returns true if given id is in the list of
-     * enabled extra checks. See addEnabled()
+     * enabled extra checks (--enable)
      * @param str id for the extra check, e.g. "style"
      * @return true if the check is enabled.
      */
     bool isEnabled(const std::string &str) const;
 
     /**
-     * Enable extra checks by id. See isEnabled()
+     * @brief Enable extra checks by id. See isEnabled()
      * @param str single id or list of id values to be enabled
      * or empty string to enable all. e.g. "style,possibleError"
      */
     void addEnabled(const std::string &str);
 
-    /** class for handling suppressions */
+    /** @brief class for handling suppressions */
     class Suppressions
     {
     private:
-        /** List of error which the user doesn't want to see. */
+        /** @brief List of error which the user doesn't want to see. */
         std::map<std::string, std::map<std::string, std::list<int> > > _suppressions;
     public:
         /**
-         * Don't show errors listed in the file.
+         * @brief Don't show errors listed in the file.
          * @param istr Open file stream where errors can be read.
          * @return true on success, false in syntax error is noticed.
          */
         bool parseFile(std::istream &istr);
 
         /**
-         * Don't show this error. If file and/or line are optional. In which case
+         * @brief Don't show this error. If file and/or line are optional. In which case
          * the errorId alone is used for filtering.
          * @param errorId the id for the error, e.g. "arrayIndexOutOfBounds"
          * @param file File name with the path, e.g. "src/main.cpp"
@@ -160,10 +171,10 @@ public:
 
     };
 
-    /** suppress message */
+    /** @brief suppress message (--suppressions) */
     Suppressions nomsg;
 
-    /** suppress exitcode */
+    /** @brief suppress exitcode */
     Suppressions nofail;
 };