Merge topic 'doxygen-fixes'

09ff226 Merge branch 'add-const-qualifiers' into doxygen-fixes
31ab25c doxygen: MathCommand is not about string operators
486033a doxygen: review cmake.h
937bb4b doxygen: remove a few comments
4774590 doxygen: fix some comments in cmPolicies.h
4a48be3 doxygen: Small fixes in cmake.h apidocs
1e5b971 doxygen: Use proper syntax to document enum
54ab11c doxygen: Improve API docs of GetRealDependency
80072d4 doxygen: cmPropertyDefinition

11 files changed, 121 insertions, 147 deletions

diff --git a/Source/cmForEachCommand.h b/Source/cmForEachCommand.h
index 0386981..ae50005 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 815a693..43c8e29 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 ba97922..83ea8a4 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/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);
 
diff --git a/Source/cmMacroCommand.h b/Source/cmMacroCommand.h
index 65ad5b9..36e4b2f 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/cmMathCommand.h b/Source/cmMathCommand.h
index 88654dd..d622904 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:
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
+ * <a href="http://www.cmake.org/Wiki/CMake/Policies">policies</a>
+ * 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
   };
 
diff --git a/Source/cmPropertyDefinition.h b/Source/cmPropertyDefinition.h
index 58d1472..16bd148 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() const { 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;
 };
 
diff --git a/Source/cmWhileCommand.h b/Source/cmWhileCommand.h
index 3a1bd5b..e111ae4 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:
diff --git a/Source/cmake.h b/Source/cmake.h
index 31b1bb7..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:
@@ -66,31 +68,33 @@ 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<cmStdString, cmCommand*> 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/";};
@@ -164,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();