diff options
Diffstat (limited to 'Modules/FindDoxygen.cmake')
| -rw-r--r-- | Modules/FindDoxygen.cmake | 79 |
1 files changed, 45 insertions, 34 deletions
diff --git a/Modules/FindDoxygen.cmake b/Modules/FindDoxygen.cmake index 81fbbb7..bbf941e 100644 --- a/Modules/FindDoxygen.cmake +++ b/Modules/FindDoxygen.cmake @@ -6,8 +6,7 @@ FindDoxygen ----------- Doxygen is a documentation generation tool (see http://www.doxygen.org). -This module looks for Doxygen and some optional tools it supports. These -tools are enabled as components in the :command:`find_package` command: +This module looks for Doxygen and some optional tools it supports: ``dot`` `Graphviz <http://graphviz.org>`_ ``dot`` utility used to render various @@ -19,7 +18,9 @@ tools are enabled as components in the :command:`find_package` command: `Dia <https://wiki.gnome.org/Apps/Dia>`_ the diagram editor used by Doxygen's ``\diafile`` command. -Examples: +.. versionadded:: 3.9 + These tools are available as components in the :command:`find_package` command. + For example: .. code-block:: cmake @@ -38,12 +39,13 @@ The following variables are defined by this module: The version reported by ``doxygen --version``. -The module defines ``IMPORTED`` targets for Doxygen and each component found. -These can be used as part of custom commands, etc. and should be preferred over -old-style (and now deprecated) variables like ``DOXYGEN_EXECUTABLE``. The -following import targets are defined if their corresponding executable could be -found (the component import targets will only be defined if that component was -requested): +.. versionadded:: 3.9 + The module defines ``IMPORTED`` targets for Doxygen and each component found. + These can be used as part of custom commands, etc. and should be preferred over + old-style (and now deprecated) variables like ``DOXYGEN_EXECUTABLE``. The + following import targets are defined if their corresponding executable could be + found (the component import targets will only be defined if that component was + requested): :: @@ -58,6 +60,8 @@ Functions .. command:: doxygen_add_docs + .. versionadded:: 3.9 + This function is intended as a convenience for adding a target for generating documentation with Doxygen. It aims to provide sensible defaults so that projects can generally just provide the input files and directories and that @@ -93,19 +97,21 @@ Functions the :command:`add_custom_target` command used to create the custom target internally. - If ``ALL`` is set, the target will be added to the default build target. - - If ``USE_STAMP_FILE`` is set, the custom command defined by this function will - create a stamp file with the name ``<targetName>.stamp`` in the current - binary directory whenever doxygen is re-run. With this option present, all - items in ``<filesOrDirs>`` must be files (i.e. no directories, symlinks or - wildcards) and each of the files must exist at the time - ``doxygen_add_docs()`` is called. An error will be raised if any of the - items listed is missing or is not a file when ``USE_STAMP_FILE`` is given. - A dependency will be created on each of the files so that doxygen will only - be re-run if one of the files is updated. Without the ``USE_STAMP_FILE`` - option, doxygen will always be re-run if the ``<targetName>`` target is built - regardless of whether anything listed in ``<filesOrDirs>`` has changed. + .. versionadded:: 3.12 + If ``ALL`` is set, the target will be added to the default build target. + + .. versionadded:: 3.16 + If ``USE_STAMP_FILE`` is set, the custom command defined by this function will + create a stamp file with the name ``<targetName>.stamp`` in the current + binary directory whenever doxygen is re-run. With this option present, all + items in ``<filesOrDirs>`` must be files (i.e. no directories, symlinks or + wildcards) and each of the files must exist at the time + ``doxygen_add_docs()`` is called. An error will be raised if any of the + items listed is missing or is not a file when ``USE_STAMP_FILE`` is given. + A dependency will be created on each of the files so that doxygen will only + be re-run if one of the files is updated. Without the ``USE_STAMP_FILE`` + option, doxygen will always be re-run if the ``<targetName>`` target is built + regardless of whether anything listed in ``<filesOrDirs>`` has changed. The contents of the generated ``Doxyfile`` can be customized by setting CMake variables before calling ``doxygen_add_docs()``. Any variable with a name of @@ -308,18 +314,19 @@ if they contain at least one space: WARN_LOGFILE XML_OUTPUT -There are situations where it may be undesirable for a particular config option -to be automatically quoted by ``doxygen_add_docs()``, such as ``ALIASES`` which -may need to include its own embedded quoting. The ``DOXYGEN_VERBATIM_VARS`` -variable can be used to specify a list of Doxygen variables (including the -leading ``DOXYGEN_`` prefix) which should not be quoted. The project is then -responsible for ensuring that those variables' values make sense when placed -directly in the Doxygen input file. In the case of list variables, list items -are still separated by spaces, it is only the automatic quoting that is -skipped. For example, the following allows ``doxygen_add_docs()`` to apply -quoting to ``DOXYGEN_PROJECT_BRIEF``, but not each item in the -``DOXYGEN_ALIASES`` list (:ref:`bracket syntax <Bracket Argument>` can also -be used to make working with embedded quotes easier): +.. versionadded:: 3.11 + There are situations where it may be undesirable for a particular config option + to be automatically quoted by ``doxygen_add_docs()``, such as ``ALIASES`` which + may need to include its own embedded quoting. The ``DOXYGEN_VERBATIM_VARS`` + variable can be used to specify a list of Doxygen variables (including the + leading ``DOXYGEN_`` prefix) which should not be quoted. The project is then + responsible for ensuring that those variables' values make sense when placed + directly in the Doxygen input file. In the case of list variables, list items + are still separated by spaces, it is only the automatic quoting that is + skipped. For example, the following allows ``doxygen_add_docs()`` to apply + quoting to ``DOXYGEN_PROJECT_BRIEF``, but not each item in the + ``DOXYGEN_ALIASES`` list (:ref:`bracket syntax <Bracket Argument>` can also + be used to make working with embedded quotes easier): .. code-block:: cmake @@ -341,6 +348,8 @@ The resultant ``Doxyfile`` will contain the following lines: Deprecated Result Variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. deprecated:: 3.9 + For compatibility with previous versions of CMake, the following variables are also defined but they are deprecated and should no longer be used: @@ -375,6 +384,8 @@ are also defined but they are deprecated and should no longer be used: Deprecated Hint Variables ^^^^^^^^^^^^^^^^^^^^^^^^^ +.. deprecated:: 3.9 + .. variable:: DOXYGEN_SKIP_DOT This variable has no effect for the component form of ``find_package``. |