summaryrefslogtreecommitdiffstats
path: root/Modules/FindDoxygen.cmake
diff options
context:
space:
mode:
authorCraig Scott <craig.scott@crascit.com>2017-12-27 13:13:39 (GMT)
committerCraig Scott <craig.scott@crascit.com>2018-01-02 20:59:59 (GMT)
commit1e6d1dd358dc7aace3a1effa4f1646e1272be3dc (patch)
tree74933f72b5f914d98603b2b64464673d42766db6 /Modules/FindDoxygen.cmake
parent497f4bb941a84bacfca2392759de6cb8e23b0684 (diff)
downloadCMake-1e6d1dd358dc7aace3a1effa4f1646e1272be3dc.zip
CMake-1e6d1dd358dc7aace3a1effa4f1646e1272be3dc.tar.gz
CMake-1e6d1dd358dc7aace3a1effa4f1646e1272be3dc.tar.bz2
FindDoxygen: Add DOXYGEN_VERBATIM_VARS for quote prevention
Each CMake variable listed in DOXYGEN_VERBATIM_VARS will not have any automatic quoting applied to it when written to the Doxyfile.
Diffstat (limited to 'Modules/FindDoxygen.cmake')
-rw-r--r--Modules/FindDoxygen.cmake59
1 files changed, 51 insertions, 8 deletions
diff --git a/Modules/FindDoxygen.cmake b/Modules/FindDoxygen.cmake
index d0dd0f1..8aea4e0 100644
--- a/Modules/FindDoxygen.cmake
+++ b/Modules/FindDoxygen.cmake
@@ -244,7 +244,7 @@ required form if set.
TAGFILES
TCL_SUBST
-The following single value Doxygen options would be quoted automatically
+The following single value Doxygen options will be quoted automatically
if they contain at least one space:
::
@@ -292,6 +292,36 @@ 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):
+
+.. code-block:: cmake
+
+ set(DOXYGEN_PROJECT_BRIEF "String with spaces")
+ set(DOXYGEN_ALIASES
+ [[somealias="@some_command param"]]
+ "anotherAlias=@foobar"
+ )
+ set(DOXYGEN_VERBATIM_VARS DOXYGEN_ALIASES)
+
+The resultant ``Doxyfile`` will contain the following lines:
+
+.. code-block:: text
+
+ PROJECT_BRIEF = "String with spaces"
+ ALIASES = somealias="@some_command param" anotherAlias=@foobar
+
+
Deprecated Result Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -331,7 +361,7 @@ Deprecated Hint Variables
.. variable:: DOXYGEN_SKIP_DOT
- This variable has no any effect for component form of ``find_package``.
+ This variable has no effect for the component form of ``find_package``.
In backward compatibility mode (i.e. without components list) it prevents
the finder module from searching for Graphviz's ``dot`` utility.
@@ -716,12 +746,15 @@ endif()
function(doxygen_quote_value VARIABLE)
# Quote a value of the given variable if:
- # - variable parameter was really given
- # - a variable it points is defined
- # - a value doesn't quoted already
- # - and it has spaces
+ # - VARIABLE parameter was really given
+ # - the variable it names is defined and is not present in the list
+ # specified by DOXYGEN_VERBATIM_VARS (if set)
+ # - the value of the named variable isn't already quoted
+ # - the value has spaces
if(VARIABLE AND DEFINED ${VARIABLE} AND
- NOT ${VARIABLE} MATCHES "^\".* .*\"$" AND ${VARIABLE} MATCHES " ")
+ NOT ${VARIABLE} MATCHES "^\".* .*\"$" AND ${VARIABLE} MATCHES " " AND
+ NOT (DEFINED DOXYGEN_VERBATIM_VARS AND
+ "${VARIABLE}" IN_LIST DOXYGEN_VERBATIM_VARS))
set(${VARIABLE} "\"${${VARIABLE}}\"" PARENT_SCOPE)
endif()
endfunction()
@@ -730,8 +763,18 @@ function(doxygen_list_to_quoted_strings LIST_VARIABLE)
if(LIST_VARIABLE AND DEFINED ${LIST_VARIABLE})
unset(_inputs)
unset(_sep)
+ unset(_verbatim)
+ # Have to test if list items should be treated as verbatim here
+ # because we lose the variable name when we pass just one list item
+ # to doxygen_quote_value() below
+ if(DEFINED DOXYGEN_VERBATIM_VARS AND
+ "${LIST_VARIABLE}" IN_LIST DOXYGEN_VERBATIM_VARS)
+ set(_verbatim True)
+ endif()
foreach(_in IN LISTS ${LIST_VARIABLE})
- doxygen_quote_value(_in)
+ if(NOT _verbatim)
+ doxygen_quote_value(_in)
+ endif()
string(APPEND _inputs "${_sep}${_in}")
set(_sep " ")
endforeach()