From 80072d4ebfd2bc431649298618e040e1eba5822f Mon Sep 17 00:00:00 2001 From: "Yury G. Kudryashov" Date: Tue, 28 Feb 2012 17:05:54 +0400 Subject: doxygen: cmPropertyDefinition --- Source/cmPropertyDefinition.h | 35 +++++++++++++++++++++++------------ 1 file changed, 23 insertions(+), 12 deletions(-) diff --git a/Source/cmPropertyDefinition.h b/Source/cmPropertyDefinition.h index f68db87..4a3c887 100644 --- a/Source/cmPropertyDefinition.h +++ b/Source/cmPropertyDefinition.h @@ -14,45 +14,56 @@ #include "cmProperty.h" -class cmPropertyDefinition +/** \class cmPropertyDefinition + * \brief Property meta-information + * + * This class contains the following meta-information about property: + * - Name; + * - Various documentation strings; + * - The scope of the property; + * - If the property is chained. + */ +class cmPropertyDefinition { public: - // Define this property + /// Define this property void DefineProperty(const char *name, cmProperty::ScopeType scope, const char *ShortDescription, const char *FullDescription, const char *DocumentationSection, bool chained); - // get the documentation string + /// Get the documentation string cmDocumentationEntry GetDocumentation() const; - // basic constructor + /// Default constructor cmPropertyDefinition() { this->Chained = false; }; - // is it chained? + /// Is the property chained? bool IsChained() {return this->Chained; }; - // Get the section if any + /// Get the section if any const std::string &GetDocumentationSection() const { return this->DocumentationSection; }; - - // get the scope + + /// Get the scope cmProperty::ScopeType GetScope() const { return this->Scope; }; - // get the docs + /// Get the documentation (short version) const std::string &GetShortDescription() const { - return this->ShortDescription; }; + return this->ShortDescription; }; + + /// Get the documentation (full version) const std::string &GetFullDescription() const { return this->FullDescription; }; - + protected: std::string Name; std::string ShortDescription; std::string FullDescription; std::string DocumentationSection; - cmProperty::ScopeType Scope; + cmProperty::ScopeType Scope; bool Chained; }; -- cgit v0.12 From 54ab11c0d23fcd015ec2e5686524ac9c746ed0ca Mon Sep 17 00:00:00 2001 From: "Yury G. Kudryashov" Date: Sat, 25 Feb 2012 13:16:07 +0400 Subject: doxygen: Improve API docs of GetRealDependency Use list instead of sequence of sentences in one paragraph. --- Source/cmLocalGenerator.h | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/Source/cmLocalGenerator.h b/Source/cmLocalGenerator.h index 0c5b9d0..c3d057f 100644 --- a/Source/cmLocalGenerator.h +++ b/Source/cmLocalGenerator.h @@ -160,15 +160,18 @@ public: void AppendFeatureOptions(std::string& flags, const char* lang, const char* feature); - /** Translate a dependency as given in CMake code to the name to - appear in a generated build file. If the given name is that of - a utility target, returns false. If the given name is that of - a CMake target it will be transformed to the real output - location of that target for the given configuration. If the - given name is the full path to a file it will be returned. - Otherwise the name is treated as a relative path with respect to - the source directory of this generator. This should only be - used for dependencies of custom commands. */ + /** \brief Get absolute path to dependency \a name + * + * Translate a dependency as given in CMake code to the name to + * appear in a generated build file. + * - If \a name is a utility target, returns false. + * - If \a name is a CMake target, it will be transformed to the real output + * location of that target for the given configuration. + * - If \a name is the full path to a file, it will be returned. + * - Otherwise \a name is treated as a relative path with respect to + * the source directory of this generator. This should only be + * used for dependencies of custom commands. + */ bool GetRealDependency(const char* name, const char* config, std::string& dep); -- cgit v0.12 From 1e5b971ed0346849243ecbcd05443404ebf7a3cb Mon Sep 17 00:00:00 2001 From: "Yury G. Kudryashov" Date: Sun, 26 Feb 2012 02:21:39 +0400 Subject: doxygen: Use proper syntax to document enum --- Source/cmake.h | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/Source/cmake.h b/Source/cmake.h index 31b1bb7..cfa747e 100644 --- a/Source/cmake.h +++ b/Source/cmake.h @@ -66,21 +66,24 @@ class cmake }; - /** Describes the working modes of cmake. - * NORMAL_MODE: cmake runs to create project files - * SCRIPT_MODE: in script mode there is no generator and no cache. Also, - * language are not enabled, so add_executable and things do - * not do anything. Started by using -P - * FIND_PACKAGE_MODE: cmake runs in pkg-config like mode, i.e. it just - * searches for a package and prints the results to stdout. - * This is similar to SCRIPT_MODE, but commands like - * add_library() work too, since they may be used e.g. in - * exported target files. Started via --find-package - */ + /** \brief Describes the working modes of cmake */ enum WorkingMode { - NORMAL_MODE, + NORMAL_MODE, ///< Cmake runs to create project files + /** \brief Script mode (started by using -P). + * + * In script mode there is no generator and no cache. Also, + * languages are not enabled, so add_executable and things do + * nothing. + */ SCRIPT_MODE, + /** \brief A pkg-config like mode + * + * In this mode cmake just searches for a package and prints the results to + * stdout. This is similar to SCRIPT_MODE, but commands like add_library() + * work too, since they may be used e.g. in exported target files. Started + * via --find-package. + */ FIND_PACKAGE_MODE }; typedef std::map RegisteredCommandsMap; -- cgit v0.12 From 4a48be323bfc9e7e3089bd1bef3141cd1b397f7f Mon Sep 17 00:00:00 2001 From: "Yury G. Kudryashov" Date: Sun, 26 Feb 2012 02:36:38 +0400 Subject: doxygen: Small fixes in cmake.h apidocs --- Source/cmake.h | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Source/cmake.h b/Source/cmake.h index cfa747e..3558374 100644 --- a/Source/cmake.h +++ b/Source/cmake.h @@ -88,12 +88,11 @@ class cmake }; typedef std::map RegisteredCommandsMap; - ///! construct an instance of cmake + /// Default constructor cmake(); - ///! destruct an instance of cmake + /// Destructor ~cmake(); - ///! construct an instance of cmake static const char *GetCMakeFilesDirectory() {return "/CMakeFiles";}; static const char *GetCMakeFilesDirectoryPostSlash() { return "CMakeFiles/";}; -- cgit v0.12 From 477459010f78d0d6d563080466a63490b6b99eb9 Mon Sep 17 00:00:00 2001 From: "Yury G. Kudryashov" Date: Sun, 26 Feb 2012 15:54:41 +0400 Subject: doxygen: fix some comments in cmPolicies.h --- Source/cmPolicies.h | 63 +++++++++++++++++++++++++++++++++-------------------- 1 file changed, 39 insertions(+), 24 deletions(-) diff --git a/Source/cmPolicies.h b/Source/cmPolicies.h index 2160f37..3106248 100644 --- a/Source/cmPolicies.h +++ b/Source/cmPolicies.h @@ -21,8 +21,9 @@ class cmPolicy; /** \class cmPolicies * \brief Handles changes in CMake behavior and policies * - * See the cmake wiki section on policies for an overview of this class's - * purpose + * See the cmake wiki section on + * policies + * for an overview of this class's purpose */ class cmPolicies { @@ -30,32 +31,46 @@ public: cmPolicies(); ~cmPolicies(); - enum PolicyStatus { OLD, WARN, NEW, REQUIRED_IF_USED, REQUIRED_ALWAYS }; + /// Status of a policy + enum PolicyStatus { + OLD, ///< Use old behavior + WARN, ///< Use old behavior but issue a warning + NEW, ///< Use new behavior + /// Issue an error if user doesn't set policy status to NEW and hits the + /// check + REQUIRED_IF_USED, + REQUIRED_ALWAYS ///< Issue an error unless user sets policy status to NEW. + }; static const char* PolicyStatusNames[]; + /// Policy identifiers enum PolicyID { - CMP0000, // Policy version specification - CMP0001, // Ignore old compatibility variable - CMP0002, // Target names must be unique - CMP0003, // Linking does not include extra -L paths - CMP0004, // Libraries linked may not have leading or trailing whitespace - CMP0005, // Definition value escaping - CMP0006, // BUNDLE install rules needed for MACOSX_BUNDLE targets - CMP0007, // list command handling of empty elements - CMP0008, // Full-path libraries must be a valid library file name - CMP0009, // GLOB_RECURSE should not follow symlinks by default - CMP0010, // Bad variable reference syntax is an error - CMP0011, // Strong policy scope for include and find_package - CMP0012, // Recognize numbers and boolean constants in if() - CMP0013, // Duplicate binary directories not allowed - CMP0014, // Input directories must have CMakeLists.txt - CMP0015, // link_directories() treats paths relative to source dir - CMP0016, // target_link_libraries() fails if only argument is not a target - CMP0017, // Prefer files in CMAKE_ROOT when including from CMAKE_ROOT - - // Always the last entry. Useful mostly to avoid adding a comma - // the last policy when adding a new one. + CMP0000, ///< Policy version specification + CMP0001, ///< Ignore old compatibility variable + CMP0002, ///< Target names must be unique + CMP0003, ///< Linking does not include extra -L paths + CMP0004, ///< Libraries linked may not have leading or trailing whitespace + CMP0005, ///< Definition value escaping + CMP0006, ///< BUNDLE install rules needed for MACOSX_BUNDLE targets + CMP0007, ///< list command handling of empty elements + CMP0008, ///< Full-path libraries must be a valid library file name + CMP0009, ///< GLOB_RECURSE should not follow symlinks by default + CMP0010, ///< Bad variable reference syntax is an error + CMP0011, ///< Strong policy scope for include and find_package + CMP0012, ///< Recognize numbers and boolean constants in if() + CMP0013, ///< Duplicate binary directories not allowed + CMP0014, ///< Input directories must have CMakeLists.txt + CMP0015, ///< link_directories() treats paths relative to source dir + /// target_link_libraries() fails if only argument is not a target + CMP0016, + CMP0017, ///< Prefer files in CMAKE_ROOT when including from CMAKE_ROOT + + /** \brief Always the last entry. + * + * Useful mostly to avoid adding a comma the last policy when adding a new + * one. + */ CMPCOUNT }; -- cgit v0.12 From 937bb4bebf560fddeb2a1438939fd50d177ae2bf Mon Sep 17 00:00:00 2001 From: "Yury G. Kudryashov" Date: Tue, 28 Feb 2012 01:54:43 +0400 Subject: doxygen: remove a few comments These comments were either wrong or non-informative. Replace some of them by brief comments --- Source/cmForEachCommand.h | 11 +---------- Source/cmFunctionBlocker.h | 5 ----- Source/cmFunctionCommand.h | 11 +---------- Source/cmIfCommand.h | 11 +---------- Source/cmMacroCommand.h | 11 +---------- Source/cmWhileCommand.h | 11 +---------- 6 files changed, 5 insertions(+), 55 deletions(-) diff --git a/Source/cmForEachCommand.h b/Source/cmForEachCommand.h index 026fd31..e702173 100644 --- a/Source/cmForEachCommand.h +++ b/Source/cmForEachCommand.h @@ -16,11 +16,6 @@ #include "cmFunctionBlocker.h" #include "cmListFileCache.h" -/** \class cmForEachFunctionBlocker - * \brief subclass of function blocker - * - * - */ class cmForEachFunctionBlocker : public cmFunctionBlocker { public: @@ -37,11 +32,7 @@ private: int Depth; }; -/** \class cmForEachCommand - * \brief starts an if block - * - * cmForEachCommand starts an if block - */ +/// Starts foreach() ... endforeach() block class cmForEachCommand : public cmCommand { public: diff --git a/Source/cmFunctionBlocker.h b/Source/cmFunctionBlocker.h index c3b29e1..9ee0b5c 100644 --- a/Source/cmFunctionBlocker.h +++ b/Source/cmFunctionBlocker.h @@ -17,11 +17,6 @@ #include "cmListFileCache.h" class cmMakefile; -/** \class cmFunctionBlocker - * \brief A class that defines an interface for blocking cmake functions - * - * This is the superclass for any classes that need to block a cmake function - */ class cmFunctionBlocker { public: diff --git a/Source/cmFunctionCommand.h b/Source/cmFunctionCommand.h index a169244..9873964 100644 --- a/Source/cmFunctionCommand.h +++ b/Source/cmFunctionCommand.h @@ -15,11 +15,6 @@ #include "cmCommand.h" #include "cmFunctionBlocker.h" -/** \class cmFunctionFunctionBlocker - * \brief subclass of function blocker - * - * - */ class cmFunctionFunctionBlocker : public cmFunctionBlocker { public: @@ -35,11 +30,7 @@ public: int Depth; }; -/** \class cmFunctionCommand - * \brief starts an if block - * - * cmFunctionCommand starts an if block - */ +/// Starts function() ... endfunction() block class cmFunctionCommand : public cmCommand { public: diff --git a/Source/cmIfCommand.h b/Source/cmIfCommand.h index 4996bc4..f412442 100644 --- a/Source/cmIfCommand.h +++ b/Source/cmIfCommand.h @@ -15,11 +15,6 @@ #include "cmCommand.h" #include "cmFunctionBlocker.h" -/** \class cmIfFunctionBlocker - * \brief subclass of function blocker - * - * - */ class cmIfFunctionBlocker : public cmFunctionBlocker { public: @@ -39,11 +34,7 @@ public: unsigned int ScopeDepth; }; -/** \class cmIfCommand - * \brief starts an if block - * - * cmIfCommand starts an if block - */ +/// Starts an if block class cmIfCommand : public cmCommand { public: diff --git a/Source/cmMacroCommand.h b/Source/cmMacroCommand.h index 93e10b2..03aa72d 100644 --- a/Source/cmMacroCommand.h +++ b/Source/cmMacroCommand.h @@ -15,11 +15,6 @@ #include "cmCommand.h" #include "cmFunctionBlocker.h" -/** \class cmMacroFunctionBlocker - * \brief subclass of function blocker - * - * - */ class cmMacroFunctionBlocker : public cmFunctionBlocker { public: @@ -35,11 +30,7 @@ public: int Depth; }; -/** \class cmMacroCommand - * \brief starts an if block - * - * cmMacroCommand starts an if block - */ +/// Starts macro() ... endmacro() block class cmMacroCommand : public cmCommand { public: diff --git a/Source/cmWhileCommand.h b/Source/cmWhileCommand.h index 04649a3..1947fcf 100644 --- a/Source/cmWhileCommand.h +++ b/Source/cmWhileCommand.h @@ -16,11 +16,6 @@ #include "cmFunctionBlocker.h" #include "cmListFileCache.h" -/** \class cmWhileFunctionBlocker - * \brief subclass of function blocker - * - * - */ class cmWhileFunctionBlocker : public cmFunctionBlocker { public: @@ -37,11 +32,7 @@ private: int Depth; }; -/** \class cmWhileCommand - * \brief starts a while loop - * - * cmWhileCommand starts a while loop - */ +/// \brief Starts a while loop class cmWhileCommand : public cmCommand { public: -- cgit v0.12 From 486033aef302d122938e6f52fd1c7ad29a5e75a5 Mon Sep 17 00:00:00 2001 From: "Yury G. Kudryashov" Date: Tue, 28 Feb 2012 16:44:54 +0400 Subject: doxygen: review cmake.h * Move top-level comment to class apidocs * Remove misleading comment --- Source/cmake.h | 52 ++++++++++++++++++++++++---------------------------- 1 file changed, 24 insertions(+), 28 deletions(-) diff --git a/Source/cmake.h b/Source/cmake.h index 3558374..161e656 100644 --- a/Source/cmake.h +++ b/Source/cmake.h @@ -9,28 +9,6 @@ implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the License for more information. ============================================================================*/ -// This class represents a cmake invocation. It is the top level class when -// running cmake. Most cmake based GUIS should primarily create an instance -// of this class and communicate with it. -// -// The basic process for a GUI is as follows: -// -// 1) Create a cmake instance -// 2) Set the Home & Start directories, generator, and cmake command. this -// can be done using the Set methods or by using SetArgs and passing in -// command line arguments. -// 3) Load the cache by calling LoadCache (duh) -// 4) if you are using command line arguments with -D or -C flags then -// call SetCacheArgs (or if for some other reason you want to modify the -// cache, do it now. -// 5) Finally call Configure -// 6) Let the user change values and go back to step 5 -// 7) call Generate -// -// If your GUI allows the user to change the start & home directories then -// you must at a minimum redo steps 2 through 7. -// - #ifndef cmake_h #define cmake_h @@ -53,6 +31,30 @@ class cmListFileBacktrace; class cmTarget; class cmGeneratedFileStream; +/** \brief Represents a cmake invocation. + * + * This class represents a cmake invocation. It is the top level class when + * running cmake. Most cmake based GUIS should primarily create an instance + * of this class and communicate with it. + * + * The basic process for a GUI is as follows: + * + * -# Create a cmake instance + * -# Set the Home & Start directories, generator, and cmake command. this + * can be done using the Set methods or by using SetArgs and passing in + * command line arguments. + * -# Load the cache by calling LoadCache (duh) + * -# if you are using command line arguments with -D or -C flags then + * call SetCacheArgs (or if for some other reason you want to modify the + * cache), do it now. + * -# Finally call Configure + * -# Let the user change values and go back to step 5 + * -# call Generate + + * If your GUI allows the user to change the start & home directories then + * you must at a minimum redo steps 2 through 7. + */ + class cmake { public: @@ -166,12 +168,6 @@ class cmake int Configure(); int ActualConfigure(); - /** - * Configure the cmMakefiles. This routine will create a GlobalGenerator if - * one has not already been set. It will then Call Configure on the - * GlobalGenerator. This in turn will read in an process all the CMakeList - * files for the tree. It will not produce any actual Makefiles, or - * workspaces. Generate does that. */ int LoadCache(); void PreLoadCMakeFiles(); -- cgit v0.12 From 31ab25c0c9298aa833edd118752e97f15f7d8e2a Mon Sep 17 00:00:00 2001 From: "Yury G. Kudryashov" Date: Wed, 29 Feb 2012 17:34:17 +0400 Subject: doxygen: MathCommand is not about string operators --- Source/cmMathCommand.h | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/Source/cmMathCommand.h b/Source/cmMathCommand.h index d31f34b..d45e4fc 100644 --- a/Source/cmMathCommand.h +++ b/Source/cmMathCommand.h @@ -14,10 +14,7 @@ #include "cmCommand.h" -/** \class cmMathCommand - * \brief Common string operations - * - */ +/// Mathematical expressions: math(EXPR ...) command. class cmMathCommand : public cmCommand { public: -- cgit v0.12