Skip to content
GitLab
Commit a0257415 authored by Brad King's avatar Brad King 💬
Browse files

ENH: Cleaned up documentation and formatted it for use by cmDocumentation.

parent dec0b510
Hide whitespace changes
Inline Side-by-side
Source/cmAbstractFilesCommand.h
View file @ a0257415
......@@ -44,7 +44,7 @@ public:
*/
virtual const char* GetTerseDocumentation()
{
return "Depricated command, see SET_SOURCE_FILES_PROPERTIES.";
return "Deprecated. See SET_SOURCE_FILES_PROPERTIES.";
}
/**
......@@ -53,7 +53,8 @@ public:
virtual const char* GetFullDocumentation()
{
return
"ABSTRACT_FILES(file1 file2 ..).";
" ABSTRACT_FILES(file1 file2 ...)\n"
"Marks files with the ABSTRACT property.";
}
cmTypeMacro(cmAbstractFilesCommand, cmCommand);
......
Source/cmAddCustomCommandCommand.h
View file @ a0257415
......@@ -77,7 +77,7 @@ public:
*/
virtual const char* GetTerseDocumentation()
{
return "Create new command within CMake.";
return "Add a custom build rule to the generated build system.";
}
/**
......@@ -86,24 +86,37 @@ public:
virtual const char* GetFullDocumentation()
{
return
"ADD_CUSTOM_COMMAND([SOURCE source] [COMMAND command] TARGET target "
"[ARGS [args...]] [DEPENDS [depends...]] [OUTPUTS [outputs...]] [COMMENT comment])\n"
" ADD_CUSTOM_COMMAND(TARGET target\n"
" [SOURCE source]\n"
" [COMMAND command]\n"
" [ARGS [args...]]\n"
" [DEPENDS [depends...]]\n"
" [OUTPUTS [outputs...]]\n"
" [COMMENT comment])\n"
"This defines a new command that can be executed during the build "
"process. In makefile terms this creates a new target in the following form:<pre><code>\n"
"OUTPUT1: SOURCE DEPENDS\n"
" COMAND ARGS\n"
"OUTPUT2: SOURCE DEPENDS\n"
" COMAND ARGS\n"
" Example of usage:\n"
"process. In makefile terms this creates a new target in the "
"following form:\n"
" OUTPUT1: SOURCE DEPENDS\n"
" COMAND ARGS\n"
" OUTPUT2: SOURCE DEPENDS\n"
" COMAND ARGS\n"
"The TARGET must be specified, but it is not the make target of the "
"build rule. It is the target (library, executable, or custom target) "
"that will use the output generated from this rule. This is necessary "
"to choose a project file in which to generate the rule for Visual "
"Studio.\n\n"
"Example of usage:\n"
" ADD_CUSTOM_COMMAND(\n"
" SOURCE ${VTK_TIFF_FAX_EXE} \n"
" COMMAND ${VTK_TIFF_FAX_EXE} \n"
" ARGS -c const ${VTK_BINARY_DIR}/Utilities/tiff/tif_fax3sm.c \n"
" TARGET vtktiff \n"
" OUTPUTS ${VTK_BINARY_DIR}/Utilities/tiff/tif_fax3sm.c\n"
" )\n"
"This will create custom target which will generate file tif_fax3sm.c\n"
"using command ${VTK_TIFF_FAX_EXE}.</pre></code>";
" TARGET tiff\n"
" SOURCE ${TIFF_FAX_EXE}\n"
" COMMAND ${TIFF_FAX_EXE}\n"
" ARGS -c const ${TIFF_BINARY_DIR}/tif_fax3sm.c\n"
" OUTPUTS ${TIFF_BINARY_DIR}/tif_fax3sm.c\n"
" )\n"
"This will create custom target which will generate file tif_fax3sm.c "
"using command ${TIFF_FAX_EXE}. The rule will be executed as part of "
"building the tiff library because it includes tif_fax3sm.c as a "
"source file with the GENERATED property.";
}
cmTypeMacro(cmAddCustomCommandCommand, cmCommand);
......
Source/cmAddCustomTargetCommand.h
View file @ a0257415
......@@ -55,9 +55,7 @@ public:
*/
virtual const char* GetTerseDocumentation()
{
return "Add an extra target to the build system that "
"does not produce output, so it"
" is run each time the target is built.";
return "Add a target with no output so it will always be built.";
}
/**
......@@ -66,8 +64,15 @@ public:
virtual const char* GetFullDocumentation()
{
return
"ADD_CUSTOM_TARGET(Name [ALL] [ command arg arg arg ... ])\n"
"If the ALL option is specified it indicates that this target should be added to the default build target. The command and arguments are optional. If not specified, it will create an empty target. The command cannot be called ALL.";
" ADD_CUSTOM_TARGET(Name [ALL] [ command arg arg arg ... ])\n"
"Adds a target with the given name that executes the given command "
"every time the target is built. If the ALL option is specified "
"it indicates that this target should be added to the default build "
"target so that it will be run every time. "
"The command and arguments are optional. If not specified, "
"it will create an empty target. The ADD_DEPENDENCIES command can be "
"used in conjunction with this command to drive custom target "
"generation. The command cannot be called ALL.";
}
cmTypeMacro(cmAddCustomTargetCommand, cmCommand);
......
Source/cmAddDefinitionsCommand.h
View file @ a0257415
......@@ -59,7 +59,7 @@ public:
*/
virtual const char* GetTerseDocumentation()
{
return "Add -D define flags to command line for environments.";
return "Adds -D define flags to the command line of C and C++ compilers.";
}
/**
......@@ -68,8 +68,11 @@ public:
virtual const char* GetFullDocumentation()
{
return
"ADD_DEFINITIONS(-DFOO -DBAR ...)\n"
"Add flags to command line of C and C++ compiles. This command can be used to add any flag to a compile line, but the -D flag is accepted most C/C++ compilers. Other flags may not be as portable.";
" ADD_DEFINITIONS(-DFOO -DBAR ...)\n"
"Adds flags to command line of C and C++ compilers. "
"This command can be used to add any flag to a compile line, "
"but the -D flag is accepted most C/C++ compilers. "
"Other flags may not be as portable.";
}
cmTypeMacro(cmAddDefinitionsCommand, cmCommand);
......
Source/cmAddDependenciesCommand.h
View file @ a0257415
......@@ -61,8 +61,12 @@ public:
virtual const char* GetFullDocumentation()
{
return
"ADD_DEPENDENCIES(target-name depend-target depend-target)\n"
"Add a dependency to a target. This is only used to add dependencies between one executable and another. Regular build dependencies are handled automatically.";
" ADD_DEPENDENCIES(target-name depend-target1\n"
" depend-target2 ...)\n"
"Add a dependency to a target. This is only used to add dependencies "
"between targets that cannot be inferred from the library/executable "
"links that are specified. Regular build dependencies are "
"handled automatically.";
}
cmTypeMacro(cmAddDependenciesCommand, cmCommand);
......
Source/cmAddExecutableCommand.h
View file @ a0257415
......@@ -53,7 +53,7 @@ public:
*/
virtual const char* GetTerseDocumentation()
{
return "Add an executable to the project that uses the specified source files.";
return "Add an executable to the project using the specified source files.";
}
/**
......@@ -62,10 +62,11 @@ public:
virtual const char* GetFullDocumentation()
{
return
"ADD_EXECUTABLE(exename [WIN32] source1 source2 ... sourceN)\n"
"This command adds an executable target to the current directory. "
" ADD_EXECUTABLE(exename [WIN32] source1\n"
" source2 ... sourceN)\n"
"This command adds an executable target to the current directory. "
"The executable will be built from the list of source files "
"specified. The second argument to this command can be WIN32 "
"specified. The second argument to this command can be WIN32 "
"which indicates that the executable (when compiled on windows) "
"is a windows app (using WinMain) not a console app (using main).";
}
......
Source/cmAddLibraryCommand.h
View file @ a0257415
......@@ -53,7 +53,7 @@ public:
*/
virtual const char* GetTerseDocumentation()
{
return "Add an library to the project that uses the specified source files.";
return "Add an library to the project using the specified source files.";
}
/**
......@@ -62,13 +62,15 @@ public:
virtual const char* GetFullDocumentation()
{
return
"ADD_LIBRARY(libname [SHARED | STATIC | MODULE] source1 source2 ... sourceN)\n"
"Adds a library target. SHARED, STATIC or MODULE keywords are used\n"
"to set the library type. If the keywork MODULE appears, the library\n"
"type is set to MH_BUNDLE on systems which use dyld. Systems without\n"
"dyld MODULE is treated like SHARED. If no keywords appear as the second\n"
"argument, the type defaults to the current value of BUILD_SHARED_LIBS.\n"
"If this variable is not set, the type defaults to STATIC.";
" ADD_LIBRARY(libname [SHARED | STATIC | MODULE]\n"
" source1 source2 ... sourceN)\n"
"Adds a library target. SHARED, STATIC or MODULE keywords are used "
"to set the library type. If the keyword MODULE appears, the library "
"type is set to MH_BUNDLE on systems which use dyld. On systems "
"without dyld, MODULE is treated like SHARED. If no keywords appear "
" as the second argument, the type defaults to the current value of "
"BUILD_SHARED_LIBS. If this variable is not set, the type defaults "
"to STATIC.";
}
cmTypeMacro(cmAddLibraryCommand, cmCommand);
......
Source/cmAddTestCommand.h
View file @ a0257415
......@@ -67,12 +67,12 @@ public:
virtual const char* GetFullDocumentation()
{
return
"ADD_TEST(testname Exename arg1 arg2 arg3 ...)\n"
"If the ENABLE_TESTING command has been run, this command adds a"
"test target to the current directory. If ENABLE_TESTING has not"
"been run, this command does nothing.\n"
" ADD_TEST(testname Exename arg1 arg2 ...)\n"
"If the ENABLE_TESTING command has been run, this command adds a "
"test target to the current directory. If ENABLE_TESTING has not "
"been run, this command does nothing. "
"The tests are run by the testing subsystem by executing Exename "
"with the specified arguments. Exename can be either an executable "
"with the specified arguments. Exename can be either an executable "
"built by built by this project or an arbitrary executable on the "
"system (like tclsh).";
}
......
Source/cmAuxSourceDirectoryCommand.h
View file @ a0257415
......@@ -56,8 +56,7 @@ public:
*/
virtual const char* GetTerseDocumentation()
{
return "Add all the source files found in the specified\n"
"directory to the variable name specified.";
return "Find all source files in a directory.";
}
/**
......@@ -66,7 +65,9 @@ public:
virtual const char* GetFullDocumentation()
{
return
"AUX_SOURCE_DIRECTORY(dir VARIABLE)";
" AUX_SOURCE_DIRECTORY(dir VARIABLE)\n"
"Collects the names of all the source files in the specified "
"directory and stores the list in the variable provided.";
}
cmTypeMacro(cmAuxSourceDirectoryCommand, cmCommand);
......
Source/cmBuildCommand.h
View file @ a0257415
......@@ -58,7 +58,7 @@ public:
*/
virtual const char* GetTerseDocumentation()
{
return "Determine the command line that will build this project.";
return "Get the command line that will build this project.";
}
/**
......@@ -67,8 +67,12 @@ public:
virtual const char* GetFullDocumentation()
{
return
"BUILD_COMMAND(NAME MAKECOMMAND)\n"
"Within CMAKE set NAME to the command that will build this project from the command line using MAKECOMMAND. MAKECOMMAND should be msdev, nmake, make or one of the end use build tools. This command will construct the command line to use that will build all the targets in this project. This is useful for testing systems.";
" BUILD_COMMAND(variable MAKECOMMAND)\n"
"Sets the given variable to a string containing the command that "
"will build this project from the root of the build tree using the "
"build tool given by MAKECOMMAND. MAKECOMMAND should be msdev, "
"nmake, make or one of the end user build tools. "
"This is useful for configuring testing systems.";
}
cmTypeMacro(cmBuildCommand, cmCommand);
......
Source/cmBuildNameCommand.h
View file @ a0257415
......@@ -58,7 +58,7 @@ public:
*/
virtual const char* GetTerseDocumentation()
{
return "Depricated command. Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER} instead..";
return "Depricated. Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER} instead.";
}
/**
......@@ -67,8 +67,10 @@ public:
virtual const char* GetFullDocumentation()
{
return
"BUILD_NAME(NAME)\n"
"Within CMAKE sets NAME to the build type.";
" BUILD_NAME(variable)\n"
"Sets the specified variable to a string representing the platform "
"and compiler settings. These values are now available through the "
"CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.";
}
cmTypeMacro(cmBuildNameCommand, cmCommand);
......
Source/cmConfigureFileCommand.h
View file @ a0257415
......@@ -44,7 +44,7 @@ public:
*/
virtual const char* GetTerseDocumentation()
{
return "Create a file from an autoconf style file.in file.";
return "Copy a file to another location and modify its contents.";
}
/**
......@@ -53,19 +53,21 @@ public:
virtual const char* GetFullDocumentation()
{
return
"CONFIGURE_FILE(InputFile OutputFile [COPYONLY] [ESCAPE_QUOTES] [IMMEDIATE] [@ONLY])\n"
"The Input and Ouput files have to have full paths.\n"
"They can also use variables like CMAKE_BINARY_DIR,CMAKE_SOURCE_DIR. "
"This command replaces any variables in the input file with their "
"values as determined by CMake. If a variables in not defined, it "
"will be replaced with nothing. If COPYONLY is passed in, then "
"then no variable expansion will take place. If ESCAPE_QUOTES is "
"passed in then any substitued quotes will be C style escaped. "
" CONFIGURE_FILE(InputFile OutputFile\n"
" [COPYONLY] [ESCAPE_QUOTES]\n"
" [IMMEDIATE] [@ONLY])\n"
"The Input and Ouput files have to have full paths. "
"This command replaces any variables in the input file referenced as "
"${VAR} or @VAR@ with their values as determined by CMake. If a "
"variable is not defined, it will be replaced with nothing. "
"If COPYONLY is specified, then then no variable expansion will take "
"place. If ESCAPE_QUOTES is specified in then any substitued quotes "
"will be C-style escaped. "
"If IMMEDIATE is specified, then the file will be configured with "
"the current values of CMake variables instead of waiting until the "
"end of CMakeLists processing. If @ONLY is present, only variables "
"of the form @var@ will be replaces and ${var} will be ignored. "
"This is useful for configuring tcl scripts that use ${var}.";
"end of CMakeLists processing. If @ONLY is specified, only variables "
"of the form @VAR@ will be replaces and ${VAR} will be ignored. "
"This is useful for configuring tcl scripts that use ${VAR}.";
}
virtual void FinalPass();
......
Source/cmCreateTestSourceList.h
View file @ a0257415
......@@ -67,10 +67,16 @@ public:
virtual const char* GetFullDocumentation()
{
return
"CREATE_TEST_SOURCELIST(SourceListName DriverName test1 test2 test3 "
"EXTRA_INCLUDE include.h FUNCTION function) The list of source files "
"needed to build the testdriver will be in SourceListName. "
"DriverName is the name of the test driver program. The rest of "
" CREATE_TEST_SOURCELIST(SourceListName DriverName\n"
" test1 test2 test3\n"
" EXTRA_INCLUDE include.h\n"
" FUNCTION function)\n"
"A test driver is a program that links together many small tests into "
"a single executable. This is useful when building static executables "
"with large libraries to shrink the total required size. "
"The list of source files "
"needed to build the testdriver will be in SourceListName. "
"DriverName is the name of the test driver program. The rest of "
"the arguments consist of a list of test source files, can be "
"; separated. Each test source file should have a function in it that "
"is the same name as the file with no extension (foo.cxx should have "
......
Source/cmElseCommand.h
View file @ a0257415
......@@ -57,7 +57,7 @@ public:
*/
virtual const char* GetTerseDocumentation()
{
return "starts the else portion of an if block";
return "Starts the ELSE portion of an IF block.";
}
/**
......@@ -66,7 +66,8 @@ public:
virtual const char* GetFullDocumentation()
{
return
"ELSE(args), Note that the args for the ELSE clause must match those of the IF clause. See the IF command for more information.";
" ELSE(expression)\n"
"See IF command.";
}
cmTypeMacro(cmElseCommand, cmCommand);
......
Source/cmEnableTestingCommand.h
View file @ a0257415
......@@ -74,7 +74,7 @@ public:
*/
virtual const char* GetTerseDocumentation()
{
return "Enable testing for this directory and below.";
return "Enable testing for current directory and below.";
}
/**
......@@ -83,8 +83,11 @@ public:
virtual const char* GetFullDocumentation()
{
return
"ENABLE_TESTING()\n"
"Enables testing for this directory and below. See also the ADD_TEST command. Note that Dart expects to find this file in the build directory root; therefore, this command should be in the source directory root too.";
" ENABLE_TESTING()\n"
"Enables testing for this directory and below. "
"See also the ADD_TEST command. Note that Dart expects to find "
"a test file in the build directory root. Therefore, this command "
"should be in the source directory root too.";
}
cmTypeMacro(cmEnableTestingCommand, cmCommand);
......
Source/cmEndForEachCommand.h
View file @ a0257415
......@@ -64,7 +64,7 @@ public:
*/
virtual const char* GetTerseDocumentation()
{
return "ends a foreach block";
return "Ends a list of commands in a FOREACH block.";
}
/**
......@@ -72,7 +72,9 @@ public:
*/
virtual const char* GetFullDocumentation()
{
return "ENDFOREACH(define)";
return
" ENDFOREACH(expression)\n"
"See FOREACH command.";
}
cmTypeMacro(cmEndForEachCommand, cmCommand);
......
Source/cmEndIfCommand.h
View file @ a0257415
......@@ -57,7 +57,7 @@ public:
*/
virtual const char* GetTerseDocumentation()
{
return "ends an if block";
return "Ends a list of commands in an IF block.";
}
/**
......@@ -66,7 +66,8 @@ public:
virtual const char* GetFullDocumentation()
{
return
"ENDIF(define)";
" ENDIF(expression)\n"
"See IF command.";
}
cmTypeMacro(cmEndIfCommand, cmCommand);
......
Source/cmExecProgramCommand.h
View file @ a0257415
......@@ -64,12 +64,16 @@ public:
virtual const char* GetFullDocumentation()
{
return
"EXEC_PROGRAM(Executable [Directory to run in] [ARGS arguments to executable] [OUTPUT_VARIABLE var] [RETURN_VALUE var])"
"The executable is run in the optionally specified Directory. The executable "
"can include arguments if it is double quoted, but it is better to use the "
"optional ARGS argument to specify arguments to the program. This is because "
"cmake will then be able to escape spaces in the Executable path. An optiona "
"argument OUTPUT_VARIABLE specifies a variable to which the output will be set. "
" EXEC_PROGRAM(Executable [directory in which to run]\n"
" [ARGS <arguments to executable>]\n"
" [OUTPUT_VARIABLE <var>]\n"
" [RETURN_VALUE <var>])\n"
"The executable is run in the optionally specified Directory. The "
"executable can include arguments if it is double quoted, but it is "
"better to use the optional ARGS argument to specify arguments to the "
"program. This is because cmake will then be able to escape spaces "
"in the Executable path. An optional argument OUTPUT_VARIABLE "
"specifies a variable in which to store the output. "
"To capture the return value of the execution, use RETURN_VALUE variable. "
"If OUTPUT_VARIABLE is specified, then no output will go to the stdout/stderr "
"of the console running cmake.";
......
Source/cmExportLibraryDependencies.h
View file @ a0257415
......@@ -67,12 +67,14 @@ public:
virtual const char* GetFullDocumentation()
{
return
"EXPORT_LIBRARY_DEPENDENCIES(FILE [APPEND])\n"
"Create a file that can be included into a cmakelist file with the "
"INCLUDE command. The file will contain a number of SET commands "
" EXPORT_LIBRARY_DEPENDENCIES(FILE [APPEND])\n"
"Create a file that can be included into a CMake listfile with the "
"INCLUDE command. The file will contain a number of SET commands "
"that will set all the variables needed for library dependency "
"information. This should be the last command in the top level "
"CMakeLists.txt file of the project.";
"CMakeLists.txt file of the project. If the APPEND option is "
"specified, the SET commands will be appended to the given file "
"instead of replacing it.";
}
cmTypeMacro(cmExportLibraryDependenciesCommand, cmCommand);
......
Source/cmFLTKWrapUICommand.h
View file @ a0257415
......@@ -69,12 +69,11 @@ public:
virtual const char* GetFullDocumentation()
{
return
"FLTK_WRAP_UI(resultingLibraryName source1 source2 ... sourceN )\n"
"Produce .h and .cxx files for all the .fl and .fld file listed.\n"
"The .h files will be added to the library using the base name in\n"
"source list.\n"
"The .cxx files will be added to the library using the base name in \n"
"source list.";
" FLTK_WRAP_UI(resultingLibraryName source1\n"
" source2 ... sourceN )\n"
"Produce .h and .cxx files for all the .fl and .fld files listed. "
"The resulting .h and .cxx files will be added to the specified "
"library.";
}
private:
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment