ENH: Improve ctest_* command documentation

This corrects the terse documentation and adds detail to the full
documentation of some commands.  It also normalizes the layout of the
documentation string endings to make adding lines easier.

6 files changed, 36 insertions, 19 deletions

diff --git a/Source/CTest/cmCTestBuildCommand.h b/Source/CTest/cmCTestBuildCommand.h
index a961388..18e23d7 100644
--- a/Source/CTest/cmCTestBuildCommand.h
+++ b/Source/CTest/cmCTestBuildCommand.h
@@ -55,7 +55,7 @@ public:
    */
   virtual const char* GetTerseDocumentation()
     {
-    return "Builds the repository.";
+    return "Build the project.";
     }
   virtual bool InitialPass(std::vector<std::string> const& args,
                            cmExecutionStatus &status);
@@ -65,9 +65,15 @@ public:
   virtual const char* GetFullDocumentation()
     {
     return
-      "  ctest_build([BUILD build_dir] [RETURN_VALUE res] "
-      " [NUMBER_ERRORS val] [NUMBER_WARNINGS val])\n"
-      "Builds the given build directory and stores results in Build.xml.";
+      "  ctest_build([BUILD build_dir] [RETURN_VALUE res]\n"
+      "              [NUMBER_ERRORS val] [NUMBER_WARNINGS val])\n"
+      "Builds the given build directory and stores results in Build.xml. "
+      "If no BUILD is given, the CTEST_BINARY_DIRECTORY variable is used. "
+      "The RETURN_VALUE option specifies a variable in which to store the "
+      "return value of the native build tool. "
+      "The NUMBER_ERRORS and NUMBER_WARNINGS options specify variables in "
+      "which to store the number of build errors and warnings detected."
+      ;
     }
 
   cmTypeMacro(cmCTestBuildCommand, cmCTestHandlerCommand);
diff --git a/Source/CTest/cmCTestConfigureCommand.h b/Source/CTest/cmCTestConfigureCommand.h
index 7284fd7..b0210d2 100644
--- a/Source/CTest/cmCTestConfigureCommand.h
+++ b/Source/CTest/cmCTestConfigureCommand.h
@@ -50,7 +50,7 @@ public:
    */
   virtual const char* GetTerseDocumentation()
     {
-    return "Configures the repository.";
+    return "Configure the project build tree.";
     }
 
   /**
@@ -59,12 +59,17 @@ public:
   virtual const char* GetFullDocumentation()
     {
     return
-      "  ctest_configure(BUILD build_dir OPTIONS options RETURN_VALUE res)\n"
+      "  ctest_configure([BUILD build_dir] [SOURCE source_dir]\n"
+      "                  [OPTIONS options] [RETURN_VALUE res])\n"
       "Configures the given build directory and stores results in "
-      "Configure.xml. The OPTIONS arguments are passed as command line "
-      "arguments to the configure command. "
-      "The RETURN_VALUE argument is a variable that will hold "
-      "the return value.";
+      "Configure.xml. "
+      "If no BUILD is given, the CTEST_BINARY_DIRECTORY variable is used. "
+      "If no SOURCE is given, the CTEST_SOURCE_DIRECTORY variable is used. "
+      "The OPTIONS argument specifies command line arguments to pass to "
+      "the configuration tool. "
+      "The RETURN_VALUE option specifies a variable in which to store the "
+      "return value of the native build tool."
+      ;
     }
 
   cmTypeMacro(cmCTestConfigureCommand, cmCTestHandlerCommand);
diff --git a/Source/CTest/cmCTestCoverageCommand.h b/Source/CTest/cmCTestCoverageCommand.h
index e9ae426..89f6df5 100644
--- a/Source/CTest/cmCTestCoverageCommand.h
+++ b/Source/CTest/cmCTestCoverageCommand.h
@@ -51,7 +51,7 @@ public:
    */
   virtual const char* GetTerseDocumentation()
     {
-    return "Tests the repository.";
+    return "Collect coverage tool results.";
     }
 
   /**
@@ -63,7 +63,8 @@ public:
       "  ctest_coverage([BUILD build_dir] [RETURN_VALUE res])\n"
       "Perform the coverage of the given build directory and stores results "
       "in Coverage.xml. The second argument is a variable that will hold "
-      "value.";
+      "value."
+      ;
     }
 
   cmTypeMacro(cmCTestCoverageCommand, cmCTestHandlerCommand);
diff --git a/Source/CTest/cmCTestMemCheckCommand.h b/Source/CTest/cmCTestMemCheckCommand.h
index b55bbf1..a2a692f 100644
--- a/Source/CTest/cmCTestMemCheckCommand.h
+++ b/Source/CTest/cmCTestMemCheckCommand.h
@@ -53,7 +53,7 @@ public:
    */
   virtual const char* GetTerseDocumentation()
     {
-    return "Tests the repository.";
+    return "Run tests with a dynamic analysis tool.";
     }
 
   /**
@@ -65,7 +65,8 @@ public:
       "  ctest_memcheck([BUILD build_dir] [RETURN_VALUE res])\n"
       "Performs a memory checking of tests in the given build directory and "
       "stores results in MemCheck.xml. The second argument is a variable "
-      "that will hold value.";
+      "that will hold value."
+      ;
     }
 
   cmTypeMacro(cmCTestMemCheckCommand, cmCTestTestCommand);
diff --git a/Source/CTest/cmCTestTestCommand.h b/Source/CTest/cmCTestTestCommand.h
index 03ed7a1..4a65faa 100644
--- a/Source/CTest/cmCTestTestCommand.h
+++ b/Source/CTest/cmCTestTestCommand.h
@@ -51,7 +51,7 @@ public:
    */
   virtual const char* GetTerseDocumentation()
     {
-    return "Tests the repository.";
+    return "Run tests in the project build tree.";
     }
 
   /**
@@ -73,7 +73,8 @@ public:
       "expression for tests to run INCLUDE, or a regular expression for tests "
       "to not run EXCLUDE. EXCLUDE_LABEL and INCLUDE_LABEL are regular "
       "expression for test to be included or excluded by the test "
-      "property LABEL.";
+      "property LABEL."
+      ;
     }
 
   cmTypeMacro(cmCTestTestCommand, cmCTestHandlerCommand);
diff --git a/Source/CTest/cmCTestUpdateCommand.h b/Source/CTest/cmCTestUpdateCommand.h
index 117013c..6bcdd23 100644
--- a/Source/CTest/cmCTestUpdateCommand.h
+++ b/Source/CTest/cmCTestUpdateCommand.h
@@ -51,7 +51,7 @@ public:
    */
   virtual const char* GetTerseDocumentation()
     {
-    return "Updates the repository.";
+    return "Update the work tree from version control.";
     }
 
   /**
@@ -62,8 +62,11 @@ public:
     return
       "  ctest_update([SOURCE source] [RETURN_VALUE res])\n"
       "Updates the given source directory and stores results in Update.xml. "
-      "The second argument is a variable that will hold the number of files "
-      "modified. If there is a problem, the variable will be -1.";
+      "If no SOURCE is given, the CTEST_SOURCE_DIRECTORY variable is used. "
+      "The RETURN_VALUE option specifies a variable in which to store the "
+      "result, which is -1 on error, non-negative for success, and positive "
+      "if there are local modifications in the work tree."
+      ;
     }
 
   cmTypeMacro(cmCTestUpdateCommand, cmCTestHandlerCommand);