Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Address a peculiarity in Doxygen ALIASES in docu #770

Merged
merged 1 commit into from
Feb 13, 2022
Merged

Address a peculiarity in Doxygen ALIASES in docu #770

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 29 additions & 9 deletions documentation/source/markups.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ with the markup **embed:rst**. This means that a comment block like this::
Inserting additional reStructuredText information.
\verbatim embed:rst
.. note::

This reStructuredText has been handled correctly.
\endverbatim
*/
Expand Down Expand Up @@ -164,17 +164,12 @@ Aliases

.. cpp:namespace:: @ex_markups_aliases

To make these blocks appears as more appropriate doxygen-like markup in your
To make these blocks appear as more appropriate doxygen-like markup in your
comments you can add the following aliases to your doxygen configuration file::

ALIASES = "rst=\verbatim embed:rst"
ALIASES = "rst=^^\verbatim embed:rst^^"
ALIASES += "endrst=\endverbatim"

And, if you use leading asterisks then perhaps::

ALIASES += "rststar=\verbatim embed:rst:leading-asterisk"
ALIASES += "endrststar=\endverbatim"

Which allow you to write comments like::

/*!
Expand All @@ -185,7 +180,7 @@ Which allow you to write comments like::
This is some funky non-xml compliant text: <& !><

.. note::

This reStructuredText has been handled correctly.
\endrst

Expand All @@ -203,4 +198,29 @@ Which will be rendered as:
.. doxygenfunction:: TestClass::function
:project: rst

.. note::

The character sequence ``^^`` in an ALIAS definition inserts a line break.
The leading ``^^`` ensures that a RST ``\verbatim`` block never starts in a brief description
(which would break the output), even if you put it on the first line of a comment.
The trailing ``^^`` allows to start with RST content on the same line of the ``\rst`` command.

The ALIAS given above only works for comment blocks without a leading comment character on each line.
If you use a comment style with a leading comment character on each new line,
use these aliases instead::

ALIASES = "rst=^^\verbatim embed:rst:leading-asterisk^^"
ALIASES += "endrst=\endverbatim"

Due to an `undocumented behavior in doxygen <https://github.com/doxygen/doxygen/issues/8907>`_,
all leading comment characters (``*``, ``///`` or ``//!``) encountered in a verbatim section
will be converted to asterisk (``*`` ) by Doxygen, when ``\verbatim`` is part of an alias.
Therefore, the ALIAS above works in all comment blocks with leading line comment characters.

If you want to hide reStructuredText output from Doxygen html and only include it in sphinx,
use the Doxygen command ``\xmlonly``.
This is an example alias that enables all RST sections in XML only::

ALIASES = "rst=^^\xmlonly<verbatim>embed:rst:leading-asterisk^^"
ALIASES += "endrst=</verbatim>\endxmlonly"