Merge topic 'doc-signatures'

e1519edd91 Help: Use signature directive for the 'add_library' command
bfc9e71d1f Help: Use signature directive for the 'add_executable' command

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !9044

2 files changed, 211 insertions, 175 deletions

diff --git a/Help/command/add_executable.rst b/Help/command/add_executable.rst
index d9ea0da..b6833b4 100644
--- a/Help/command/add_executable.rst
+++ b/Help/command/add_executable.rst
@@ -10,15 +10,28 @@ Add an executable to the project using the specified source files.
 Normal Executables
 ^^^^^^^^^^^^^^^^^^
 
-.. code-block:: cmake
+.. signature::
+  add_executable(<name> <options>... <sources>...)
+  :target: normal
 
-  add_executable(<name> [WIN32] [MACOSX_BUNDLE]
-                 [EXCLUDE_FROM_ALL]
-                 [source1] [source2 ...])
+  Add an executable target called ``<name>`` to be built from the source
+  files listed in the command invocation.
 
-Adds an executable target called ``<name>`` to be built from the source
-files listed in the command invocation.  The
-``<name>`` corresponds to the logical target name and must be globally
+  The options are:
+
+  ``WIN32``
+    Set the :prop_tgt:`WIN32_EXECUTABLE` target property automatically.
+    See documentation of that target property for details.
+
+  ``MACOSX_BUNDLE``
+    Set the :prop_tgt:`MACOSX_BUNDLE` target property automatically.
+    See documentation of that target property for details.
+
+  ``EXCLUDE_FROM_ALL``
+    Set the :prop_tgt:`EXCLUDE_FROM_ALL` target property automatically.
+    See documentation of that target property for details.
+
+The ``<name>`` corresponds to the logical target name and must be globally
 unique within a project.  The actual file name of the executable built is
 constructed based on conventions of the native platform (such as
 ``<name>.exe`` or just ``<name>``).
@@ -39,18 +52,6 @@ command was invoked.  See documentation of the
 location.  See documentation of the :prop_tgt:`OUTPUT_NAME` target property
 to change the ``<name>`` part of the final file name.
 
-If ``WIN32`` is given the property :prop_tgt:`WIN32_EXECUTABLE` will be
-set on the target created.  See documentation of that target property for
-details.
-
-If ``MACOSX_BUNDLE`` is given the corresponding property will be set on
-the created target.  See documentation of the :prop_tgt:`MACOSX_BUNDLE`
-target property for details.
-
-If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on
-the created target.  See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL`
-target property for details.
-
 See the :manual:`cmake-buildsystem(7)` manual for more on defining
 buildsystem properties.
 
@@ -61,17 +62,25 @@ within IDE.
 Imported Executables
 ^^^^^^^^^^^^^^^^^^^^
 
-.. code-block:: cmake
-
+.. signature::
   add_executable(<name> IMPORTED [GLOBAL])
+  :target: IMPORTED
+
+  Add an :ref:`IMPORTED executable target <Imported Targets>` to reference
+  an executable file located outside the project.  The target name may be
+  referenced like any target built within the project, except that by
+  default it is visible only in the directory in which it is created,
+  and below.
+
+  The options are:
+
+  ``GLOBAL``
+    Make the target name globally visible.
+
+No rules are generated to build imported targets, and the :prop_tgt:`IMPORTED`
+target property is ``True``.  Imported executables are useful for convenient
+reference from commands like :command:`add_custom_command`.
 
-An :ref:`IMPORTED executable target <Imported Targets>` references an
-executable file located outside the project.  No rules are generated to
-build it, and the :prop_tgt:`IMPORTED` target property is ``True``.  The
-target name has scope in the directory in which it is created and below, but
-the ``GLOBAL`` option extends visibility.  It may be referenced like any
-target built within the project.  ``IMPORTED`` executables are useful
-for convenient reference from commands like :command:`add_custom_command`.
 Details about the imported executable are specified by setting properties
 whose names begin in ``IMPORTED_``.  The most important such property is
 :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration version
@@ -82,14 +91,14 @@ properties for more information.
 Alias Executables
 ^^^^^^^^^^^^^^^^^
 
-.. code-block:: cmake
-
+.. signature::
   add_executable(<name> ALIAS <target>)
+  :target: ALIAS
 
-Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can
-be used to refer to ``<target>`` in subsequent commands.  The ``<name>``
-does not appear in the generated buildsystem as a make target.  The
-``<target>`` may not be an ``ALIAS``.
+  Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can
+  be used to refer to ``<target>`` in subsequent commands.  The ``<name>``
+  does not appear in the generated buildsystem as a make target.  The
+  ``<target>`` may not be an ``ALIAS``.
 
 .. versionadded:: 3.11
   An ``ALIAS`` can target a ``GLOBAL`` :ref:`Imported Target <Imported Targets>`
diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst
index 80d5dee..5b22cb1 100644
--- a/Help/command/add_library.rst
+++ b/Help/command/add_library.rst
@@ -10,18 +10,39 @@ Add a library to the project using the specified source files.
 Normal Libraries
 ^^^^^^^^^^^^^^^^
 
-.. code-block:: cmake
+.. signature::
+  add_library(<name> [<type>] [EXCLUDE_FROM_ALL] <sources>...)
+  :target: normal
+
+  Add a library target called ``<name>`` to be built from the source files
+  listed in the command invocation.
+
+  The optional ``<type>`` specifies the type of library to be created:
+
+  ``STATIC``
+    An archive of object files for use when linking other targets.
+
+  ``SHARED``
+    A dynamic library that may be linked by other targets and loaded
+    at runtime.
+
+  ``MODULE``
+    A plugin that may not be linked by other targets, but may be
+    dynamically loaded at runtime using dlopen-like functionality.
+
+  If no ``<type>`` is given the default is ``STATIC`` or ``SHARED``
+  based on the value of the :variable:`BUILD_SHARED_LIBS` variable.
 
-  add_library(<name> [STATIC | SHARED | MODULE]
-              [EXCLUDE_FROM_ALL]
-              [<source>...])
+  The options are:
 
-Adds a library target called ``<name>`` to be built from the source files
-listed in the command invocation.  The ``<name>``
-corresponds to the logical target name and must be globally unique within
-a project.  The actual file name of the library built is constructed based
-on conventions of the native platform (such as ``lib<name>.a`` or
-``<name>.lib``).
+  ``EXCLUDE_FROM_ALL``
+    Set the :prop_tgt:`EXCLUDE_FROM_ALL` target property automatically.
+    See documentation of that target property for details.
+
+The ``<name>`` corresponds to the logical target name and must be globally
+unique within a project.  The actual file name of the library built is
+constructed based on conventions of the native platform (such as
+``lib<name>.a`` or ``<name>.lib``).
 
 .. versionadded:: 3.1
   Source arguments to ``add_library`` may use "generator expressions" with
@@ -32,15 +53,8 @@ on conventions of the native platform (such as ``lib<name>.a`` or
   The source files can be omitted if they are added later using
   :command:`target_sources`.
 
-``STATIC``, ``SHARED``, or ``MODULE`` may be given to specify the type of
-library to be created.  ``STATIC`` libraries are archives of object files
-for use when linking other targets.  ``SHARED`` libraries are linked
-dynamically and loaded at runtime.  ``MODULE`` libraries are plugins that
-are not linked into other targets but may be loaded dynamically at runtime
-using dlopen-like functionality.  If no type is given explicitly the
-type is ``STATIC`` or ``SHARED`` based on whether the current value of the
-variable :variable:`BUILD_SHARED_LIBS` is ``ON``.  For ``SHARED`` and
-``MODULE`` libraries the :prop_tgt:`POSITION_INDEPENDENT_CODE` target
+For ``SHARED`` and ``MODULE`` libraries the
+:prop_tgt:`POSITION_INDEPENDENT_CODE` target
 property is set to ``ON`` automatically.
 A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK`
 target property to create an macOS Framework.
@@ -63,10 +77,6 @@ invoked.  See documentation of the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`,
 location.  See documentation of the :prop_tgt:`OUTPUT_NAME` target
 property to change the ``<name>`` part of the final file name.
 
-If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on
-the created target.  See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL`
-target property for details.
-
 See the :manual:`cmake-buildsystem(7)` manual for more on defining
 buildsystem properties.
 
@@ -77,14 +87,15 @@ within IDE.
 Object Libraries
 ^^^^^^^^^^^^^^^^
 
-.. code-block:: cmake
+.. signature::
+  add_library(<name> OBJECT <sources>...)
+  :target: OBJECT
 
-  add_library(<name> OBJECT [<source>...])
+  Add an :ref:`Object Library <Object Libraries>` to compile source files
+  without archiving or linking their object files into a library.
 
-Creates an :ref:`Object Library <Object Libraries>`.  An object library
-compiles source files but does not archive or link their object files into a
-library.  Instead other targets created by ``add_library`` or
-:command:`add_executable` may reference the objects using an expression of the
+Other targets created by ``add_library`` or :command:`add_executable`
+may reference the objects using an expression of the
 form :genex:`$\<TARGET_OBJECTS:objlib\> <TARGET_OBJECTS>` as a source, where
 ``objlib`` is the object library name.  For example:
 
@@ -109,46 +120,48 @@ consider adding at least one real source file to any target that references
 Interface Libraries
 ^^^^^^^^^^^^^^^^^^^
 
-.. code-block:: cmake
-
+.. signature::
   add_library(<name> INTERFACE)
-
-Creates an :ref:`Interface Library <Interface Libraries>`.
-An ``INTERFACE`` library target does not compile sources and does
-not produce a library artifact on disk.  However, it may have
-properties set on it and it may be installed and exported.
-Typically, ``INTERFACE_*`` properties are populated on an interface
-target using the commands:
-
-* :command:`set_property`,
-* :command:`target_link_libraries(INTERFACE)`,
-* :command:`target_link_options(INTERFACE)`,
-* :command:`target_include_directories(INTERFACE)`,
-* :command:`target_compile_options(INTERFACE)`,
-* :command:`target_compile_definitions(INTERFACE)`, and
-* :command:`target_sources(INTERFACE)`,
-
-and then it is used as an argument to :command:`target_link_libraries`
-like any other target.
-
-An interface library created with the above signature has no source files
-itself and is not included as a target in the generated buildsystem.
-
-.. versionadded:: 3.15
-  An interface library can have :prop_tgt:`PUBLIC_HEADER` and
-  :prop_tgt:`PRIVATE_HEADER` properties.  The headers specified by those
-  properties can be installed using the :command:`install(TARGETS)` command.
-
-.. versionadded:: 3.19
-  An interface library target may be created with source files:
-
-  .. code-block:: cmake
-
-    add_library(<name> INTERFACE [EXCLUDE_FROM_ALL] [<source>...])
-
-  Source files may be listed directly in the ``add_library`` call or added
-  later by calls to :command:`target_sources` with the ``PRIVATE`` or
-  ``PUBLIC`` keywords.
+  :target: INTERFACE
+
+  Add an :ref:`Interface Library <Interface Libraries>` target that may
+  specify usage requirements for dependents but does not compile sources
+  and does not produce a library artifact on disk.
+
+  An interface library with no source files is not included as a target
+  in the generated buildsystem.  However, it may have
+  properties set on it and it may be installed and exported.
+  Typically, ``INTERFACE_*`` properties are populated on an interface
+  target using the commands:
+
+  * :command:`set_property`,
+  * :command:`target_link_libraries(INTERFACE)`,
+  * :command:`target_link_options(INTERFACE)`,
+  * :command:`target_include_directories(INTERFACE)`,
+  * :command:`target_compile_options(INTERFACE)`,
+  * :command:`target_compile_definitions(INTERFACE)`, and
+  * :command:`target_sources(INTERFACE)`,
+
+  and then it is used as an argument to :command:`target_link_libraries`
+  like any other target.
+
+  .. versionadded:: 3.15
+    An interface library can have :prop_tgt:`PUBLIC_HEADER` and
+    :prop_tgt:`PRIVATE_HEADER` properties.  The headers specified by those
+    properties can be installed using the :command:`install(TARGETS)` command.
+
+.. signature::
+  add_library(<name> INTERFACE [EXCLUDE_FROM_ALL] <sources>...)
+  :target: INTERFACE-with-sources
+
+  .. versionadded:: 3.19
+
+  Add an :ref:`Interface Library <Interface Libraries>` target with
+  source files (in addition to usage requirements and properties as
+  documented by the :command:`above signature <add_library(INTERFACE)>`).
+  Source files may be listed directly in the ``add_library`` call
+  or added later by calls to :command:`target_sources` with the
+  ``PRIVATE`` or ``PUBLIC`` keywords.
 
   If an interface library has source files (i.e. the :prop_tgt:`SOURCES`
   target property is set), or header sets (i.e. the :prop_tgt:`HEADER_SETS`
@@ -158,92 +171,106 @@ itself and is not included as a target in the generated buildsystem.
   but does contain build rules for custom commands created by the
   :command:`add_custom_command` command.
 
-.. note::
-  In most command signatures where the ``INTERFACE`` keyword appears,
-  the items listed after it only become part of that target's usage
-  requirements and are not part of the target's own settings.  However,
-  in this signature of ``add_library``, the ``INTERFACE`` keyword refers
-  to the library type only.  Sources listed after it in the ``add_library``
-  call are ``PRIVATE`` to the interface library and do not appear in its
-  :prop_tgt:`INTERFACE_SOURCES` target property.
+  The options are:
+
+  ``EXCLUDE_FROM_ALL``
+    Set the :prop_tgt:`EXCLUDE_FROM_ALL` target property automatically.
+    See documentation of that target property for details.
+
+  .. note::
+    In most command signatures where the ``INTERFACE`` keyword appears,
+    the items listed after it only become part of that target's usage
+    requirements and are not part of the target's own settings.  However,
+    in this signature of ``add_library``, the ``INTERFACE`` keyword refers
+    to the library type only.  Sources listed after it in the ``add_library``
+    call are ``PRIVATE`` to the interface library and do not appear in its
+    :prop_tgt:`INTERFACE_SOURCES` target property.
 
 .. _`add_library imported libraries`:
 
 Imported Libraries
 ^^^^^^^^^^^^^^^^^^
 
-.. code-block:: cmake
-
+.. signature::
   add_library(<name> <type> IMPORTED [GLOBAL])
-
-Creates an :ref:`IMPORTED library target <Imported Targets>` called ``<name>``.
-No rules are generated to build it, and the :prop_tgt:`IMPORTED` target
-property is ``True``.  The target name has scope in the directory in which
-it is created and below, but the ``GLOBAL`` option extends visibility.
-It may be referenced like any target built within the project.
-``IMPORTED`` libraries are useful for convenient reference from commands
-like :command:`target_link_libraries`.  Details about the imported library
-are specified by setting properties whose names begin in ``IMPORTED_`` and
-``INTERFACE_``.
-
-The ``<type>`` must be one of:
-
-``STATIC``, ``SHARED``, ``MODULE``, ``UNKNOWN``
-  References a library file located outside the project.  The
-  :prop_tgt:`IMPORTED_LOCATION` target property (or its per-configuration
-  variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) specifies the
-  location of the main library file on disk:
-
-  * For a ``SHARED`` library on most non-Windows platforms, the main library
-    file is the ``.so`` or ``.dylib`` file used by both linkers and dynamic
-    loaders.  If the referenced library file has a ``SONAME`` (or on macOS,
-    has a ``LC_ID_DYLIB`` starting in ``@rpath/``), the value of that field
-    should be set in the :prop_tgt:`IMPORTED_SONAME` target property.
-    If the referenced library file does not have a ``SONAME``, but the
-    platform supports it, then  the :prop_tgt:`IMPORTED_NO_SONAME` target
-    property should be set.
-
-  * For a ``SHARED`` library on Windows, the :prop_tgt:`IMPORTED_IMPLIB`
-    target property (or its per-configuration variant
-    :prop_tgt:`IMPORTED_IMPLIB_<CONFIG>`) specifies the location of the
-    DLL import library file (``.lib`` or ``.dll.a``) on disk, and the
-    ``IMPORTED_LOCATION`` is the location of the ``.dll`` runtime
-    library (and is optional, but needed by the :genex:`TARGET_RUNTIME_DLLS`
-    generator expression).
-
-  Additional usage requirements may be specified in ``INTERFACE_*`` properties.
-
-  An ``UNKNOWN`` library type is typically only used in the implementation of
-  :ref:`Find Modules`.  It allows the path to an imported library (often found
-  using the :command:`find_library` command) to be used without having to know
-  what type of library it is.  This is especially useful on Windows where a
-  static library and a DLL's import library both have the same file extension.
-
-``OBJECT``
-  References a set of object files located outside the project.
-  The :prop_tgt:`IMPORTED_OBJECTS` target property (or its per-configuration
-  variant :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) specifies the locations of
-  object files on disk.
-  Additional usage requirements may be specified in ``INTERFACE_*`` properties.
-
-``INTERFACE``
-  Does not reference any library or object files on disk, but may
-  specify usage requirements in ``INTERFACE_*`` properties.
-
-See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties
-for more information.
+  :target: IMPORTED
+
+  Add an :ref:`IMPORTED library target <Imported Targets>` called ``<name>``.
+  The target name may be referenced like any target built within the project,
+  except that by default it is visible only in the directory in which it is
+  created, and below.
+
+  The ``<type>`` must be one of:
+
+  ``STATIC``, ``SHARED``, ``MODULE``, ``UNKNOWN``
+    References a library file located outside the project.  The
+    :prop_tgt:`IMPORTED_LOCATION` target property (or its per-configuration
+    variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) specifies the
+    location of the main library file on disk:
+
+    * For a ``SHARED`` library on most non-Windows platforms, the main library
+      file is the ``.so`` or ``.dylib`` file used by both linkers and dynamic
+      loaders.  If the referenced library file has a ``SONAME`` (or on macOS,
+      has a ``LC_ID_DYLIB`` starting in ``@rpath/``), the value of that field
+      should be set in the :prop_tgt:`IMPORTED_SONAME` target property.
+      If the referenced library file does not have a ``SONAME``, but the
+      platform supports it, then  the :prop_tgt:`IMPORTED_NO_SONAME` target
+      property should be set.
+
+    * For a ``SHARED`` library on Windows, the :prop_tgt:`IMPORTED_IMPLIB`
+      target property (or its per-configuration variant
+      :prop_tgt:`IMPORTED_IMPLIB_<CONFIG>`) specifies the location of the
+      DLL import library file (``.lib`` or ``.dll.a``) on disk, and the
+      ``IMPORTED_LOCATION`` is the location of the ``.dll`` runtime
+      library (and is optional, but needed by the :genex:`TARGET_RUNTIME_DLLS`
+      generator expression).
+
+    Additional usage requirements may be specified in ``INTERFACE_*``
+    properties.
+
+    An ``UNKNOWN`` library type is typically only used in the implementation
+    of :ref:`Find Modules`.  It allows the path to an imported library
+    (often found using the :command:`find_library` command) to be used
+    without having to know what type of library it is.  This is especially
+    useful on Windows where a static library and a DLL's import library
+    both have the same file extension.
+
+  ``OBJECT``
+    References a set of object files located outside the project.
+    The :prop_tgt:`IMPORTED_OBJECTS` target property (or its per-configuration
+    variant :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) specifies the locations of
+    object files on disk.
+    Additional usage requirements may be specified in ``INTERFACE_*``
+    properties.
+
+  ``INTERFACE``
+    Does not reference any library or object files on disk, but may
+    specify usage requirements in ``INTERFACE_*`` properties.
+
+  The options are:
+
+  ``GLOBAL``
+    Make the target name globally visible.
+
+No rules are generated to build imported targets, and the :prop_tgt:`IMPORTED`
+target property is ``True``.  Imported libraries are useful for convenient
+reference from commands like :command:`target_link_libraries`.
+
+Details about the imported library are specified by setting properties whose
+names begin in ``IMPORTED_`` and ``INTERFACE_``.  See documentation of
+such properties for more information.
 
 Alias Libraries
 ^^^^^^^^^^^^^^^
 
-.. code-block:: cmake
-
+.. signature::
   add_library(<name> ALIAS <target>)
+  :target: ALIAS
 
-Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be
-used to refer to ``<target>`` in subsequent commands.  The ``<name>`` does
-not appear in the generated buildsystem as a make target.  The ``<target>``
-may not be an ``ALIAS``.
+  Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be
+  used to refer to ``<target>`` in subsequent commands.  The ``<name>`` does
+  not appear in the generated buildsystem as a make target.  The ``<target>``
+  may not be an ``ALIAS``.
 
 .. versionadded:: 3.11
   An ``ALIAS`` can target a ``GLOBAL`` :ref:`Imported Target <Imported Targets>`