From 933289a6d7877f7a4153dcabc4d4fff2eb020728 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Marjam=C3=A4ki?= Date: Sun, 14 Mar 2010 18:55:33 +0100 Subject: [PATCH] doxygen: updated comments for Cppcheck and FileLister --- lib/cppcheck.h | 34 ++++++++++++----------- lib/filelister.h | 29 ++++++++++++++++++-- lib/settings.h | 71 ++++++++++++++++++++++++++++-------------------- 3 files changed, 86 insertions(+), 48 deletions(-) diff --git a/lib/cppcheck.h b/lib/cppcheck.h index 9d08db721..b0eca8e0e 100644 --- a/lib/cppcheck.h +++ b/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 _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 _fileContents; + CheckUnusedFunctions _checkUnusedFunctions; ErrorLogger &_errorLogger; - /** Current configuration */ + /** @brief Current preprocessor configuration */ std::string cfg; std::list _xmllist; diff --git a/lib/filelister.h b/lib/filelister.h index b8c8baecf..7aa84f641 100644 --- a/lib/filelister.h +++ b/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 &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(); /// @} diff --git a/lib/settings.h b/lib/settings.h index 7a2c4a720..9a69e3004 100644 --- a/lib/settings.h +++ b/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 _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 _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 - time. Default is 1. */ + /** @brief How many processes/threads should do checking at the same + 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 - for finding include files inside source files. */ + /** @brief List of include paths, e.g. "my/includes/" which should be used + for finding include files inside source files. (-I) */ std::list _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 - * enabled extra checks. See addEnabled() + * @brief Returns true if given id is in the list of + * 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 > > _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; };