Help, ctest: Add argument placeholders

Conventionally, CMake help modes and manuals/documentation specify
placeholders for options which take one or many values after the option
name. Several existing `ctest` options do not follow this.

Fixes: #27827

Help/manual/ctest.1.rst

@@ -472,7 +472,7 @@ The options for running tests are:
  Truncate ``tail`` (default), ``middle`` or ``head`` of test output once
  maximum output size is reached.
 
-.. option:: --overwrite
+.. option:: --overwrite <option-name>
 
  Overwrite CTest configuration option.
 
@@ -491,7 +491,7 @@ The options for running tests are:
  This option will run the tests in a random order.  It is commonly
  used to detect implicit dependencies in a test suite.
 
-.. option:: --schedule-random-seed
+.. option:: --schedule-random-seed <seed>
 
  .. versionadded:: 4.1
 
@@ -500,7 +500,7 @@ The options for running tests are:
  This option is used to allow recreating failures owing to
  random order of execution by ``--schedule-random``.
 
-.. option:: --submit-index
+.. option:: --submit-index <index>
 
  Legacy option for old Dart2 dashboard server feature.
  Do not use.
@@ -694,11 +694,11 @@ be provided to use ``--build-and-test``.  If ``--test-command`` is specified
 then that will be run after the build is complete.  Other options that affect
 this mode include:
 
-.. option:: --build-and-test
+.. option:: --build-and-test <path-to-source> <path-to-build>
 
  Switch into the build and test mode.
 
-.. option:: --build-target
+.. option:: --build-target <tgt>
 
  Specify a specific target to build.  The option can be given multiple times
  with different targets, in which case each target is built in turn.
@@ -713,7 +713,7 @@ this mode include:
 
  Skip the cmake step.
 
-.. option:: --build-run-dir
+.. option:: --build-run-dir <dir>
 
  Specify directory to run programs from.
 
@@ -723,27 +723,27 @@ this mode include:
 
  Run CMake twice.
 
-.. option:: --build-exe-dir
+.. option:: --build-exe-dir <dir>
 
  Specify the directory for the executable.
 
-.. option:: --build-generator
+.. option:: --build-generator <generator-name>
 
  Specify the generator to use. See the :manual:`cmake-generators(7)` manual.
 
-.. option:: --build-generator-platform
+.. option:: --build-generator-platform <platform-name>
 
  Specify the generator-specific platform.
 
-.. option:: --build-generator-toolset
+.. option:: --build-generator-toolset <toolset-name>
 
  Specify the generator-specific toolset.
 
-.. option:: --build-project
+.. option:: --build-project <project-name>
 
  Specify the name of the project to build.
 
-.. option:: --build-makeprogram
+.. option:: --build-makeprogram <program-name>
 
  Specify the explicit make program to be used by CMake when configuring and
  building the project. Only applicable for Make and Ninja based generators.
@@ -752,26 +752,26 @@ this mode include:
 
  Skip the make clean step.
 
-.. option:: --build-config-sample
+.. option:: --build-config-sample <exe-name>
 
  A sample executable to use to determine the configuration that
  should be used.  e.g.  ``Debug``, ``Release`` etc.
 
-.. option:: --build-options
+.. option:: --build-options [<options>...]
 
  Additional options for configuring the build (i.e. for CMake, not for
  the build tool).  Note that if this is specified, the ``--build-options``
  keyword and its arguments must be the last option given on the command
  line, with the possible exception of ``--test-command``.
 
-.. option:: --test-command
+.. option:: --test-command <command>
 
  The command to run as the test step with the
  :ctest-option:`--build-and-test` option.
  All arguments following this keyword will be assumed to be part of the
  test command line, so it must be the last option given.
 
-.. option:: --test-timeout
+.. option:: --test-timeout <timeout>
 
  The time limit in seconds
 

Source/ctest.cxx

@@ -127,32 +127,39 @@ cmDocumentationEntry const cmDocumentationOptions[] = {
     "Disable timing summary information for "
     "subprojects." },
   { "--test-dir <dir>", "Specify the directory in which to look for tests." },
-  { "--build-and-test", "Configure, build and run a test." },
-  { "--build-target", "Specify a specific target to build." },
+  { "--build-and-test <path-to-source> <path-to-build>",
+    "Configure, build and run a test." },
+  { "--build-target <tgt>", "Specify a specific target to build." },
   { "--build-nocmake", "Run the build without running cmake first." },
-  { "--build-run-dir", "Specify directory to run programs from." },
+  { "--build-run-dir <dir>", "Specify directory to run programs from." },
   { "--build-two-config", "Run CMake twice" },
-  { "--build-exe-dir", "Specify the directory for the executable." },
-  { "--build-generator", "Specify the generator to use." },
-  { "--build-generator-platform", "Specify the generator-specific platform." },
-  { "--build-generator-toolset", "Specify the generator-specific toolset." },
-  { "--build-project", "Specify the name of the project to build." },
-  { "--build-makeprogram", "Specify the make program to use." },
+  { "--build-exe-dir <dir>", "Specify the directory for the executable." },
+  { "--build-generator <generator-name>", "Specify the generator to use." },
+  { "--build-generator-platform <platform-name>",
+    "Specify the generator-specific platform." },
+  { "--build-generator-toolset <toolset-name>",
+    "Specify the generator-specific toolset." },
+  { "--build-project <project-name>",
+    "Specify the name of the project to build." },
+  { "--build-makeprogram <program-name>", "Specify the make program to use." },
   { "--build-noclean", "Skip the make clean step." },
-  { "--build-config-sample",
-    "A sample executable to use to determine the configuration" },
-  { "--build-options", "Add extra options to the build step." },
-
-  { "--test-command", "The test to run with the --build-and-test option." },
-  { "--test-timeout", "The time limit in seconds, internal use only." },
-  { "--test-load", "CPU load threshold for starting new parallel tests." },
+  { "--build-config-sample <exe-name>",
+    "A sample executable to use to determine the configuration." },
+  { "--build-options [<options>...]", "Add extra options to the build step." },
+  { "--test-command <command>",
+    "The test to run with the --build-and-test option." },
+  { "--test-timeout <timeout>",
+    "The time limit in seconds, internal use only." },
+  { "--test-load <level>",
+    "CPU load threshold for starting new parallel tests." },
   { "--tomorrow-tag", "Nightly or experimental starts with next day tag." },
-  { "--overwrite", "Overwrite CTest configuration option." },
+  { "--overwrite <option-name>", "Overwrite CTest configuration option." },
   { "--extra-submit <file>[;<file>]", "Submit extra files to the dashboard." },
   { "--http-header <header>", "Append HTTP header when submitting" },
   { "--schedule-random", "Use a random order for scheduling tests" },
-  { "--schedule-random-seed", "Override seed for random order of tests" },
-  { "--submit-index",
+  { "--schedule-random-seed <seed>",
+    "Override seed for random order of tests" },
+  { "--submit-index <index>",
     "Submit individual dashboard tests with specific index" },
   { "--timeout <seconds>", "Set the default test timeout." },
   { "--stop-time <time>",