Commit e33d8d2d authored by Brad King's avatar Brad King

Drop builtin command documentation

Drop all GetTerseDocumentation and GetFullDocumentation methods from
commands.  The command documentation is now in Help/command/*.rst files.
parent 399e9c46
......@@ -160,8 +160,6 @@ set(SRCS
cmDocumentation.cxx
cmDocumentationFormatter.cxx
cmDocumentationSection.cxx
cmDocumentGeneratorExpressions.h
cmDocumentLocationUndefined.h
cmDynamicLoader.cxx
cmDynamicLoader.h
${ELF_SRCS}
......
......@@ -45,34 +45,8 @@ public:
*/
virtual const char* GetName() const { return "ctest_build";}
/**
* Succinct documentation.
*/
virtual const char* GetTerseDocumentation() const
{
return "Build the project.";
}
virtual bool InitialPass(std::vector<std::string> const& args,
cmExecutionStatus &status);
/**
* More documentation.
*/
virtual const char* GetFullDocumentation() const
{
return
" ctest_build([BUILD build_dir] [TARGET target] [RETURN_VALUE res]\n"
" [APPEND][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.\n"
"The TARGET variable can be used to specify a build target. If none "
"is specified, the \"all\" target will be built.\n"
"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."
"\n"
CTEST_COMMAND_APPEND_OPTION_DOCS;
}
cmTypeMacro(cmCTestBuildCommand, cmCTestHandlerCommand);
......
......@@ -40,34 +40,6 @@ public:
*/
virtual const char* GetName() const { return "ctest_configure";}
/**
* Succinct documentation.
*/
virtual const char* GetTerseDocumentation() const
{
return "Configure the project build tree.";
}
/**
* More documentation.
*/
virtual const char* GetFullDocumentation() const
{
return
" 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. "
"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."
"\n"
CTEST_COMMAND_APPEND_OPTION_DOCS;
}
cmTypeMacro(cmCTestConfigureCommand, cmCTestHandlerCommand);
protected:
......
......@@ -41,32 +41,6 @@ public:
*/
virtual const char* GetName() const { return "ctest_coverage";}
/**
* Succinct documentation.
*/
virtual const char* GetTerseDocumentation() const
{
return "Collect coverage tool results.";
}
/**
* More documentation.
*/
virtual const char* GetFullDocumentation() const
{
return
" ctest_coverage([BUILD build_dir] [RETURN_VALUE res] [APPEND]\n"
" [LABELS label1 [label2 [...]]])\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"
"The LABELS option filters the coverage report to include only "
"source files labeled with at least one of the labels specified."
"\n"
CTEST_COMMAND_APPEND_OPTION_DOCS;
}
cmTypeMacro(cmCTestCoverageCommand, cmCTestHandlerCommand);
protected:
......
......@@ -50,26 +50,6 @@ public:
*/
virtual const char* GetName() const { return "ctest_empty_binary_directory";}
/**
* Succinct documentation.
*/
virtual const char* GetTerseDocumentation() const
{
return "empties the binary directory";
}
/**
* More documentation.
*/
virtual const char* GetFullDocumentation() const
{
return
" ctest_empty_binary_directory( directory )\n"
"Removes a binary directory. This command will perform some checks "
"prior to deleting the directory in an attempt to avoid malicious "
"or accidental directory deletion.";
}
cmTypeMacro(cmCTestEmptyBinaryDirectoryCommand, cmCTestCommand);
};
......
......@@ -43,40 +43,6 @@ public:
*/
virtual const char* GetName() const { return "ctest_memcheck";}
/**
* Succinct documentation.
*/
virtual const char* GetTerseDocumentation() const
{
return "Run tests with a dynamic analysis tool.";
}
/**
* More documentation.
*/
virtual const char* GetFullDocumentation() const
{
return
" ctest_memcheck([BUILD build_dir] [RETURN_VALUE res] [APPEND]\n"
" [START start number] [END end number]\n"
" [STRIDE stride number] [EXCLUDE exclude regex ]\n"
" [INCLUDE include regex] \n"
" [EXCLUDE_LABEL exclude regex] \n"
" [INCLUDE_LABEL label regex] \n"
" [PARALLEL_LEVEL level] )\n"
"Tests the given build directory and stores results in MemCheck.xml. "
"The second argument is a variable that will hold value. Optionally, "
"you can specify the starting test number START, the ending test number "
"END, the number of tests to skip between each test STRIDE, a regular "
"expression for tests to run INCLUDE, or a regular expression for tests "
"not to run EXCLUDE. EXCLUDE_LABEL and INCLUDE_LABEL are regular "
"expressions for tests to be included or excluded by the test "
"property LABEL. PARALLEL_LEVEL should be set to a positive number "
"representing the number of tests to be run in parallel."
"\n"
CTEST_COMMAND_APPEND_OPTION_DOCS;
}
cmTypeMacro(cmCTestMemCheckCommand, cmCTestTestCommand);
protected:
......
......@@ -48,25 +48,6 @@ public:
*/
virtual const char* GetName() const { return "ctest_read_custom_files";}
/**
* Succinct documentation.
*/
virtual const char* GetTerseDocumentation() const
{
return "read CTestCustom files.";
}
/**
* More documentation.
*/
virtual const char* GetFullDocumentation() const
{
return
" ctest_read_custom_files( directory ... )\n"
"Read all the CTestCustom.ctest or CTestCustom.cmake files from "
"the given directory.";
}
cmTypeMacro(cmCTestReadCustomFilesCommand, cmCTestCommand);
};
......
......@@ -49,30 +49,6 @@ public:
*/
virtual const char* GetName() const { return "ctest_run_script";}
/**
* Succinct documentation.
*/
virtual const char* GetTerseDocumentation() const
{
return "runs a ctest -S script";
}
/**
* More documentation.
*/
virtual const char* GetFullDocumentation() const
{
return
" ctest_run_script([NEW_PROCESS] script_file_name script_file_name1 \n"
" script_file_name2 ... [RETURN_VALUE var])\n"
"Runs a script or scripts much like if it was run from ctest -S. "
"If no argument is provided then the current script is run using "
"the current settings of the variables. If NEW_PROCESS is specified "
"then each script will be run in a separate process."
"If RETURN_VALUE is specified the return value of the last script "
"run will be put into var.";
}
cmTypeMacro(cmCTestRunScriptCommand, cmCTestCommand);
};
......
......@@ -49,26 +49,6 @@ public:
*/
virtual const char* GetName() const { return "ctest_sleep";}
/**
* Succinct documentation.
*/
virtual const char* GetTerseDocumentation() const
{
return "sleeps for some amount of time";
}
/**
* More documentation.
*/
virtual const char* GetFullDocumentation() const
{
return
" ctest_sleep(<seconds>)\n"
"Sleep for given number of seconds.\n"
" ctest_sleep(<time1> <duration> <time2>)\n"
"Sleep for t=(time1 + duration - time2) seconds if t > 0.";
}
cmTypeMacro(cmCTestSleepCommand, cmCTestCommand);
};
......
......@@ -57,30 +57,6 @@ public:
*/
virtual const char* GetName() const { return "ctest_start";}
/**
* Succinct documentation.
*/
virtual const char* GetTerseDocumentation() const
{
return "Starts the testing for a given model";
}
/**
* More documentation.
*/
virtual const char* GetFullDocumentation() const
{
return
" ctest_start(Model [TRACK <track>] [APPEND] [source [binary]])\n"
"Starts the testing for a given model. The command should be called "
"after the binary directory is initialized. If the 'source' and "
"'binary' directory are not specified, it reads the "
"CTEST_SOURCE_DIRECTORY and CTEST_BINARY_DIRECTORY. If the track is "
"specified, the submissions will go to the specified track. "
"If APPEND is used, the existing TAG is used rather than "
"creating a new one based on the current time stamp.";
}
cmTypeMacro(cmCTestStartCommand, cmCTestCommand);
private:
......
......@@ -50,44 +50,6 @@ public:
*/
virtual const char* GetName() const { return "ctest_submit";}
/**
* Succinct documentation.
*/
virtual const char* GetTerseDocumentation() const
{
return "Submit results to a dashboard server.";
}
/**
* More documentation.
*/
virtual const char* GetFullDocumentation() const
{
return
" ctest_submit([PARTS ...] [FILES ...] [RETRY_COUNT count] "
" [RETRY_DELAY delay][RETURN_VALUE res])\n"
"By default all available parts are submitted if no PARTS or FILES "
"are specified. "
"The PARTS option lists a subset of parts to be submitted. "
"Valid part names are:\n"
" Start = nothing\n"
" Update = ctest_update results, in Update.xml\n"
" Configure = ctest_configure results, in Configure.xml\n"
" Build = ctest_build results, in Build.xml\n"
" Test = ctest_test results, in Test.xml\n"
" Coverage = ctest_coverage results, in Coverage.xml\n"
" MemCheck = ctest_memcheck results, in DynamicAnalysis.xml\n"
" Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml\n"
" ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES\n"
" Submit = nothing\n"
"The FILES option explicitly lists specific files to be submitted. "
"Each individual file must exist at the time of the call.\n"
"The RETRY_DELAY option specifies how long in seconds to wait after "
"a timed-out submission before attempting to re-submit.\n"
"The RETRY_COUNT option specifies how many times to retry a timed-out "
"submission.\n";
}
cmTypeMacro(cmCTestSubmitCommand, cmCTestHandlerCommand);
protected:
......
......@@ -41,45 +41,6 @@ public:
*/
virtual const char* GetName() const { return "ctest_test";}
/**
* Succinct documentation.
*/
virtual const char* GetTerseDocumentation() const
{
return "Run tests in the project build tree.";
}
/**
* More documentation.
*/
virtual const char* GetFullDocumentation() const
{
return
" 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"
" [EXCLUDE_LABEL exclude regex] \n"
" [INCLUDE_LABEL label regex] \n"
" [PARALLEL_LEVEL level] \n"
" [SCHEDULE_RANDOM on] \n"
" [STOP_TIME time of day]) \n"
"Tests the given build directory and stores results in Test.xml. The "
"second argument is a variable that will hold value. Optionally, "
"you can specify the starting test number START, the ending test number "
"END, the number of tests to skip between each test STRIDE, a regular "
"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. PARALLEL_LEVEL should be set to a positive number "
"representing the number of tests to be run in parallel. "
"SCHEDULE_RANDOM will launch tests in a random order, and is "
"typically used to detect implicit test dependencies. STOP_TIME is the "
"time of day at which the tests should all stop running."
"\n"
CTEST_COMMAND_APPEND_OPTION_DOCS;
}
cmTypeMacro(cmCTestTestCommand, cmCTestHandlerCommand);
protected:
......
......@@ -61,10 +61,6 @@ public:
*/
virtual const char* GetName() const { return "subdirs";}
// Unused methods
virtual const char* GetTerseDocumentation() const { return ""; }
virtual const char* GetFullDocumentation() const { return ""; }
cmTypeMacro(cmCTestSubdirCommand, cmCommand);
cmCTestTestHandler* TestHandler;
......@@ -162,10 +158,6 @@ public:
*/
virtual const char* GetName() const { return "add_subdirectory";}
// Unused methods
virtual const char* GetTerseDocumentation() const { return ""; }
virtual const char* GetFullDocumentation() const { return ""; }
cmTypeMacro(cmCTestAddSubdirectoryCommand, cmCommand);
cmCTestTestHandler* TestHandler;
......@@ -252,10 +244,6 @@ public:
*/
virtual const char* GetName() const { return "add_test";}
// Unused methods
virtual const char* GetTerseDocumentation() const { return ""; }
virtual const char* GetFullDocumentation() const { return ""; }
cmTypeMacro(cmCTestAddTestCommand, cmCommand);
cmCTestTestHandler* TestHandler;
......@@ -300,10 +288,6 @@ public:
*/
virtual const char* GetName() const { return "set_tests_properties";}
// Unused methods
virtual const char* GetTerseDocumentation() const { return ""; }
virtual const char* GetFullDocumentation() const { return ""; }
cmTypeMacro(cmCTestSetTestsPropertiesCommand, cmCommand);
cmCTestTestHandler* TestHandler;
......
......@@ -41,28 +41,6 @@ public:
*/
virtual const char* GetName() const { return "ctest_update";}
/**
* Succinct documentation.
*/
virtual const char* GetTerseDocumentation() const
{
return "Update the work tree from version control.";
}
/**
* More documentation.
*/
virtual const char* GetFullDocumentation() const
{
return
" ctest_update([SOURCE source] [RETURN_VALUE res])\n"
"Updates the given source directory and stores results in Update.xml. "
"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 the number of files updated or -1 on error."
;
}
cmTypeMacro(cmCTestUpdateCommand, cmCTestHandlerCommand);
protected:
......
......@@ -45,25 +45,6 @@ public:
*/
virtual const char* GetName() const { return "ctest_upload";}
/**
* Succinct documentation.
*/
virtual const char* GetTerseDocumentation() const
{
return "Upload files to a dashboard server.";
}
/**
* More documentation.
*/
virtual const char* GetFullDocumentation() const
{
return
" ctest_upload(FILES ...)\n"
"Pass a list of files to be sent along with the build results to "
"the dashboard server.\n";
}
cmTypeMacro(cmCTestUploadCommand, cmCTestHandlerCommand);
protected:
......
......@@ -13,7 +13,6 @@
#define cmAddCompileOptionsCommand_h
#include "cmCommand.h"
#include "cmDocumentGeneratorExpressions.h"
class cmAddCompileOptionsCommand : public cmCommand
{
......@@ -38,33 +37,6 @@ public:
*/
virtual const char* GetName() const {return "add_compile_options";}
/**
* Succinct documentation.
*/
virtual const char* GetTerseDocumentation() const
{
return "Adds options to the compilation of source files.";
}
/**
* More documentation.
*/
virtual const char* GetFullDocumentation() const
{
return
" add_compile_options(<option> ...)\n"
"Adds options to the compiler command line for sources in the "
"current directory and below. This command can be used to add any "
"options, but alternative commands exist to add preprocessor "
"definitions or include directories. "
"See documentation of the directory and target COMPILE_OPTIONS "
"properties for details. "
"Arguments to add_compile_options may use \"generator "
"expressions\" with the syntax \"$<...>\". "
CM_DOCUMENT_COMMAND_GENERATOR_EXPRESSIONS
;
}
cmTypeMacro(cmAddCompileOptionsCommand, cmCommand);
};
......
......@@ -13,7 +13,6 @@
#define cmAddCustomCommandCommand_h
#include "cmCommand.h"
#include "cmDocumentGeneratorExpressions.h"
/** \class cmAddCustomCommandCommand
* \brief cmAddCustomCommandCommand defines a new command (rule) that can
......@@ -44,141 +43,6 @@ public:
*/
virtual const char* GetName() const {return "add_custom_command";}
/**
* Succinct documentation.
*/
virtual const char* GetTerseDocumentation() const
{
return "Add a custom build rule to the generated build system.";
}
/**
* More documentation.
*/
virtual const char* GetFullDocumentation() const
{
return
"There are two main signatures for add_custom_command "
"The first signature is for adding a custom command "
"to produce an output.\n"
" add_custom_command(OUTPUT output1 [output2 ...]\n"
" COMMAND command1 [ARGS] [args1...]\n"
" [COMMAND command2 [ARGS] [args2...] ...]\n"
" [MAIN_DEPENDENCY depend]\n"
" [DEPENDS [depends...]]\n"
" [IMPLICIT_DEPENDS <lang1> depend1\n"
" [<lang2> depend2] ...]\n"
" [WORKING_DIRECTORY dir]\n"
" [COMMENT comment] [VERBATIM] [APPEND])\n"
"This defines a command to generate specified OUTPUT file(s). "
"A target created in the same directory (CMakeLists.txt file) that "
"specifies any output of the custom command as a source file is given "
"a rule to generate the file using the command at build time. "
"Do not list the output in more than one independent target that may "
"build in parallel or the two instances of the rule may conflict "
"(instead use add_custom_target to drive the command and make the "
"other targets depend on that one). "
"If an output name is a relative path it will be interpreted "
"relative to the build tree directory corresponding to the current "
"source directory. "
"Note that MAIN_DEPENDENCY is completely optional and is "
"used as a suggestion to visual studio about where to hang the "
"custom command. In makefile terms this creates a new target in the "
"following form:\n"
" OUTPUT: MAIN_DEPENDENCY DEPENDS\n"
" COMMAND\n"
"If more than one command is specified they will be executed in order. "
"The optional ARGS argument is for backward compatibility and will be "
"ignored.\n"
"The second signature adds a custom command to a target "
"such as a library or executable. This is useful for "
"performing an operation before or after building the target. "
"The command becomes part of the target and will only execute "
"when the target itself is built. If the target is already built,"
" the command will not execute.\n"
" add_custom_command(TARGET target\n"
" PRE_BUILD | PRE_LINK | POST_BUILD\n"
" COMMAND command1 [ARGS] [args1...]\n"
" [COMMAND command2 [ARGS] [args2...] ...]\n"
" [WORKING_DIRECTORY dir]\n"
" [COMMENT comment] [VERBATIM])\n"
"This defines a new command that will be associated with "
"building the specified target. When the command will "
"happen is determined by which of the following is specified:\n"
" PRE_BUILD - run before all other dependencies\n"
" PRE_LINK - run after other dependencies\n"
" POST_BUILD - run after the target has been built\n"
"Note that the PRE_BUILD option is only supported on Visual "
"Studio 7 or later. For all other generators PRE_BUILD "
"will be treated as PRE_LINK.\n"
"If WORKING_DIRECTORY is specified the command will be executed "
"in the directory given. "
"If it is a relative path it will be interpreted relative to the "
"build tree directory corresponding to the current source directory. "
"If COMMENT is set, the value will be displayed as a "
"message before the commands are executed at build time. "
"If APPEND is specified the COMMAND and DEPENDS option values "
"are appended to the custom command for the first output specified. "
"There must have already been a previous call to this command with "
"the same output. The COMMENT, WORKING_DIRECTORY, and MAIN_DEPENDENCY "
"options are currently ignored when APPEND is given, "
"but may be used in the future."
"\n"
"If VERBATIM is given then all arguments to the commands will be "
"escaped properly for the build tool so that the invoked command "
"receives each argument unchanged. "
"Note that one level of escapes is still used by the CMake language "
"processor before add_custom_command even sees the arguments. "
"Use of VERBATIM is recommended as it enables correct behavior. "
"When VERBATIM is not given the behavior is platform specific because "
"there is no protection of tool-specific special characters."
"\n"
"If the output of the custom command is not actually "
"created as a file on disk it should be marked as SYMBOLIC with "
"SET_SOURCE_FILES_PROPERTIES.\n"
"The IMPLICIT_DEPENDS option requests scanning of implicit "
"dependencies of an input file. The language given specifies the "
"programming language whose corresponding dependency scanner should "
"be used. Currently only C and CXX language scanners are supported. "
"The language has to be specified for every file in the "
"IMPLICIT_DEPENDS list. "
"Dependencies discovered from the scanning are added to those of "
"the custom command at build time. Note that the IMPLICIT_DEPENDS "
"option is currently supported only for Makefile generators and "
"will be ignored by other generators."
"\n"
"If COMMAND specifies an executable target (created by "
"ADD_EXECUTABLE) it will automatically be replaced by the location "
"of the executable created at build time. Additionally a "
"target-level dependency will be added so that the executable target "
"will be built before any target using this custom command. However "
"this does NOT add a file-level dependency that would cause the "
"custom command to re-run whenever the executable is recompiled."
"\n"
"Arguments to COMMAND may use \"generator expressions\" with the "
"syntax \"$<...>\". "
CM_DOCUMENT_COMMAND_GENERATOR_EXPRESSIONS
"References to target names in generator expressions imply "
"target-level dependencies, but NOT file-level dependencies. "
"List target names with the DEPENDS option to add file dependencies."
"\n"
"The DEPENDS option specifies files on which the command depends. "
"If any dependency is an OUTPUT of another custom command in the "
"same directory (CMakeLists.txt file) CMake automatically brings the "
"other custom command into the target in which this command is built. "
"If DEPENDS is not specified the command will run whenever the OUTPUT "
"is missing; if the command does not actually create the OUTPUT then "
"the rule will always run. "
"If DEPENDS specifies any target (created by an ADD_* command) "
"a target-level dependency is created to make sure the target is "
"built before any target using this custom command. Additionally, "
"if the target is an executable or library a file-level dependency "
"is created to cause the custom command to re-run whenever the target "
"is recompiled.\n"
;
}
cmTypeMacro(cmAddCustomCommandCommand, cmCommand);
protected:
bool CheckOutputs(const std::vector<std::string>& outputs);
......