extensions: overhaul javadoc/doxygen comment parsing

doc/built-in-extensions.rst

@@ -11,15 +11,20 @@ extensions.
 hawkmoth.ext.javadoc
 --------------------
 
-This extension converts Javadoc_ comments to reStructuredText, using the
-:event:`hawkmoth-process-docstring` event.
+This extension converts Javadoc_ and Doxygen_ comments to reStructuredText,
+using the :event:`hawkmoth-process-docstring` event.
 
-.. note::
+The most commonly used commands are covered, including some inline markup, using
+either \@ or \\ command character. The support is not complete, and mainly
+covers the basic API documentation needs.
 
-   The Javadoc support is rudimentary at best.
+Note that this does not change the comment block format, only the contents of
+the comments. Only the ``/** ... */`` format is supported.
 
 .. _Javadoc: https://www.oracle.com/java/technologies/javase/javadoc.html
 
+.. _Doxygen: https://www.doxygen.nl/
+
 Installation and configuration in ``conf.py``:
 
 .. code-block:: python
@@ -31,14 +36,18 @@ Installation and configuration in ``conf.py``:
 
    Name of the transformation to handle. Defaults to ``'javadoc'``. Only convert
    the comment if the ``transform`` option matches this name, otherwise do
-   nothing.
+   nothing. Usually there's no need to modify this option.
 
 For example:
 
 .. code-block:: python
    :caption: conf.py
 
    extensions.append('hawkmoth.ext.javadoc')
+   hawkmoth_transform_default = 'javadoc'  # Transform everything
+
+:data:`hawkmoth_transform_default` sets the default for the ``transform``
+option.
 
 .. code-block:: c
    :caption: file.c
@@ -58,7 +67,6 @@ For example:
 
    .. c:autofunction:: baz
       :file: file.c
-      :transform: javadoc
 
 .. _hawkmoth.ext.napoleon:
 
@@ -81,15 +89,16 @@ Installation and configuration in ``conf.py``:
 
    Name of the transformation to handle. Defaults to ``'napoleon'``. Only
    convert the comment if the ``transform`` option matches this name, otherwise
-   do nothing.
+   do nothing. Usually there's no need to modify this option.
 
 For example:
 
 .. code-block:: python
    :caption: conf.py
 
    extensions.append('hawkmoth.ext.napoleon')
-   hawkmoth_transform_default = 'napoleon'
+   # Uncomment to transform everything, example below uses :transform: option
+   # hawkmoth_transform_default = 'napoleon'
 
 .. code-block:: c
    :caption: file.c
@@ -111,6 +120,7 @@ For example:
 
    .. c:autofunction:: baz
       :file: file.c
+      :transform: napoleon
 
 .. _hawkmoth.ext.transformations:
 

doc/examples.rst

@@ -387,8 +387,8 @@ Output
    :transform: napoleon
 
 
-Javadoc-style comments
-----------------------
+Javadoc/Doxygen-style comments
+------------------------------
 
 Source
 ~~~~~~

doc/syntax.rst

@@ -8,7 +8,7 @@ source code must be documented using specific documentation comment style, and
 the comments must follow reStructuredText markup.
 
 Optionally, the syntax may be :ref:`extended <extending-the-syntax>` to support
-e.g. Javadoc and Napoleon style comments.
+e.g. Javadoc/Doxygen and Napoleon style comments.
 
 See :ref:`the examples section <examples>` for a quick tour of what's possible,
 and read on for documentation comment formatting details.
@@ -78,11 +78,14 @@ Hawkmoth supports :ref:`extending <extending>` the syntax using :ref:`built-in
 reStructuredText.
 
 The :ref:`hawkmoth.ext.javadoc` extension provides limited support for Javadoc_
-style comments, and the :ref:`hawkmoth.ext.napoleon` extension provides support
-for :external+sphinx:py:mod:`sphinx.ext.napoleon` style comments.
+and Doxygen_ style comments, and the :ref:`hawkmoth.ext.napoleon` extension
+provides support for :external+sphinx:py:mod:`sphinx.ext.napoleon` style
+comments.
 
 .. _Javadoc: https://www.oracle.com/java/technologies/javase/javadoc.html
 
+.. _Doxygen: https://www.doxygen.nl/
+
 .. _cross-referencing:
 
 Cross-Referencing C and C++ Constructs