ENH: Document APPEND option in ctest_* commands

This adds documentation of the APPEND option to the configure, build,
test, memcheck, and coverage commands.  The docs leave specific
semantics for the dashboard server to define.

6 files changed, 20 insertions, 10 deletions

diff --git a/Source/CTest/cmCTestBuildCommand.h b/Source/CTest/cmCTestBuildCommand.h
index 18e23d7..86f5980 100644
--- a/Source/CTest/cmCTestBuildCommand.h
+++ b/Source/CTest/cmCTestBuildCommand.h
@@ -65,7 +65,7 @@ public:
   virtual const char* GetFullDocumentation()
     {
     return
-      "  ctest_build([BUILD build_dir] [RETURN_VALUE res]\n"
+      "  ctest_build([BUILD build_dir] [RETURN_VALUE res] [APPEND]\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. "
@@ -73,7 +73,8 @@ public:
       "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."
-      ;
+      "\n"
+      CTEST_COMMAND_APPEND_OPTION_DOCS;
     }
 
   cmTypeMacro(cmCTestBuildCommand, cmCTestHandlerCommand);
diff --git a/Source/CTest/cmCTestConfigureCommand.h b/Source/CTest/cmCTestConfigureCommand.h
index b0210d2..3c15658 100644
--- a/Source/CTest/cmCTestConfigureCommand.h
+++ b/Source/CTest/cmCTestConfigureCommand.h
@@ -59,7 +59,7 @@ public:
   virtual const char* GetFullDocumentation()
     {
     return
-      "  ctest_configure([BUILD build_dir] [SOURCE source_dir]\n"
+      "  ctest_configure([BUILD build_dir] [SOURCE source_dir] [APPEND]\n"
       "                  [OPTIONS options] [RETURN_VALUE res])\n"
       "Configures the given build directory and stores results in "
       "Configure.xml. "
@@ -69,7 +69,8 @@ public:
       "the configuration tool. "
       "The RETURN_VALUE option specifies a variable in which to store the "
       "return value of the native build tool."
-      ;
+      "\n"
+      CTEST_COMMAND_APPEND_OPTION_DOCS;
     }
 
   cmTypeMacro(cmCTestConfigureCommand, cmCTestHandlerCommand);
diff --git a/Source/CTest/cmCTestCoverageCommand.h b/Source/CTest/cmCTestCoverageCommand.h
index 89f6df5..3796392 100644
--- a/Source/CTest/cmCTestCoverageCommand.h
+++ b/Source/CTest/cmCTestCoverageCommand.h
@@ -60,11 +60,12 @@ public:
   virtual const char* GetFullDocumentation()
     {
     return
-      "  ctest_coverage([BUILD build_dir] [RETURN_VALUE res])\n"
+      "  ctest_coverage([BUILD build_dir] [RETURN_VALUE res] [APPEND])\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."
-      ;
+      "\n"
+      CTEST_COMMAND_APPEND_OPTION_DOCS;
     }
 
   cmTypeMacro(cmCTestCoverageCommand, cmCTestHandlerCommand);
diff --git a/Source/CTest/cmCTestHandlerCommand.h b/Source/CTest/cmCTestHandlerCommand.h
index dc123ba..7db3503 100644
--- a/Source/CTest/cmCTestHandlerCommand.h
+++ b/Source/CTest/cmCTestHandlerCommand.h
@@ -74,4 +74,9 @@ protected:
   size_t Last;
 };
 
+#define CTEST_COMMAND_APPEND_OPTION_DOCS \
+  "The APPEND option marks results for append to those previously " \
+  "submitted to a dashboard server since the last ctest_start.  " \
+  "Append semantics are defined by the dashboard server in use."
+
 #endif
diff --git a/Source/CTest/cmCTestMemCheckCommand.h b/Source/CTest/cmCTestMemCheckCommand.h
index a2a692f..00a1960 100644
--- a/Source/CTest/cmCTestMemCheckCommand.h
+++ b/Source/CTest/cmCTestMemCheckCommand.h
@@ -62,11 +62,12 @@ public:
   virtual const char* GetFullDocumentation()
     {
     return
-      "  ctest_memcheck([BUILD build_dir] [RETURN_VALUE res])\n"
+      "  ctest_memcheck([BUILD build_dir] [RETURN_VALUE res] [APPEND])\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."
-      ;
+      "\n"
+      CTEST_COMMAND_APPEND_OPTION_DOCS;
     }
 
   cmTypeMacro(cmCTestMemCheckCommand, cmCTestTestCommand);
diff --git a/Source/CTest/cmCTestTestCommand.h b/Source/CTest/cmCTestTestCommand.h
index 4a65faa..3147637 100644
--- a/Source/CTest/cmCTestTestCommand.h
+++ b/Source/CTest/cmCTestTestCommand.h
@@ -60,7 +60,7 @@ public:
   virtual const char* GetFullDocumentation()
     {
     return
-      "  ctest_test([BUILD build_dir]\n"
+      "  ctest_test([BUILD build_dir] [APPEND]\n"
       "             [START start number] [END end number]\n"
       "             [STRIDE stride number] [EXCLUDE exclude regex ]\n"
       "             [INCLUDE include regex] [RETURN_VALUE res] \n" 
@@ -74,7 +74,8 @@ public:
       "to not run EXCLUDE. EXCLUDE_LABEL and INCLUDE_LABEL are regular "
       "expression for test to be included or excluded by the test "
       "property LABEL."
-      ;
+      "\n"
+      CTEST_COMMAND_APPEND_OPTION_DOCS;
     }
 
   cmTypeMacro(cmCTestTestCommand, cmCTestHandlerCommand);