docs: Aliases for Sphinx cross references in Doxygen

- Create @CrossRef aliases to simplify adding Sphinx cross references to
  Doxygen comments.
- Add a section to the style guide about adding cross references.
- Update the comment example and drop the @def, since it isn't
  necessary.

Change-Id: Ic65b9f2111259b5a643cc043c9df2fdaf164d003
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/130830
Reviewed-by: Anthony DiGirolamo <tonymd@google.com>
Commit-Queue: Auto-Submit <auto-submit@pigweed.google.com.iam.gserviceaccount.com>
Pigweed-Auto-Submit: Wyatt Hepler <hepler@google.com>

docs/Doxyfile

@@ -285,7 +285,12 @@ TAB_SIZE               = 4
 
 ALIASES                = "rst=^^\verbatim embed:rst:leading-asterisk^^" \
                          "endrst=\endverbatim" \
-                         "rstref{1}=\verbatim embed:rst:inline :ref:`\1` \endverbatim"
+                         "rstref{1}=\verbatim embed:rst:inline :ref:`\1` \endverbatim" \
+                         "crossref{3}=\verbatim embed:rst:inline :\1:\2:`\3` \endverbatim" \
+                         "c_macro{1}=@crossref{c,macro,\1}" \
+                         "cpp_class{1}=@crossref{cpp,class,\1}" \
+                         "cpp_func{1}=@crossref{cpp,func,\1}" \
+                         "cpp_type{1}=@crossref{cpp,type,\1}"
 
 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
 # only. Doxygen will then generate output that is more tailored for C. For

docs/style_guide.rst

@@ -1230,42 +1230,40 @@ Doxygen comments in C, C++, and Java are surfaced in Sphinx using `Breathe
    Sources with doxygen comment blocks must be added to the
    ``_doxygen_input_files`` list in ``//docs/BUILD.gn`` to be processed.
 
-doxygenclass
-^^^^^^^^^^^^
-To document the members of a class use the `doxygenclass
-<https://breathe.readthedocs.io/en/latest/directives.html#doxygenclass>`_
-directive.
+Breathe provides various `directives
+<https://breathe.readthedocs.io/en/latest/directives.html>`_ for bringing
+Doxygen comments into Sphinx. These include the following:
 
-.. code-block:: rst
-
-   .. doxygenclass:: pw::sync::BinarySemaphore
-      :members:
+- `doxygenfile
+  <https://breathe.readthedocs.io/en/latest/directives.html#doxygenfile>`_ --
+  Documents everything in a source file.
+- `doxygenclass
+  <https://breathe.readthedocs.io/en/latest/directives.html#doxygenclass>`_ --
+  Documents a class and its members.
 
-Create cross reference links elsewhere in the document to functions in the above
-output with ``:cpp:class:`` or ``:cpp:func:``.
+  .. code-block:: rst
 
-.. code-block:: rst
+     .. doxygenclass:: pw::sync::BinarySemaphore
+        :members:
 
-   - :cpp:class:`pw::sync::BinarySemaphore::BinarySemaphore`
-   - :cpp:func:`pw::sync::BinarySemaphore::try_acquire`
+.. admonition:: See also
 
-.. seealso::
-   - `Breathe directives to use in rst files <https://breathe.readthedocs.io/en/latest/directives.html>`_
-   - `C++ cross reference link syntax`_
-   - `C cross reference link syntax`_
-   - `Python cross reference link syntax`_
+  `Breathe directives to use in rst files <https://breathe.readthedocs.io/en/latest/directives.html>`_
 
 Example Doxygen Comment Block
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Start a Doxygen comment block using ``///`` (three forward slashes).
 
 .. code-block:: cpp
 
-   /// @def PW_LOCK_RETURNED
+   /// This is the documentation comment for the `PW_LOCK_RETURNED()` macro. It
+   /// describes how to use the macro.
    ///
-   /// Documents a function that returns a lock without acquiring it.  For example,
-   /// a public getter method that returns a pointer to a private lock should
-   /// be annotated with `PW_LOCK_RETURNED()`.
+   /// Doxygen comments can refer to other symbols using Sphinx cross
+   /// references. For example, @cpp_class{pw::InlineBasicString}, which is
+   /// shorthand for @crossref{cpp,class,pw::InlineBasicString}, links to a C++
+   /// class. @crossref{py,func,pw_tokenizer.proto.detokenize_fields} links to a
+   /// Python function.
    ///
    /// @param[out] dest The memory area to copy to.
    /// @param[in]  src  The memory area to copy from.
@@ -1356,6 +1354,62 @@ Common Doxygen commands for use within a comment block.
 
 .. seealso:: `All Doxygen commands <https://www.doxygen.nl/manual/commands.html>`_
 
+Cross-references
+^^^^^^^^^^^^^^^^
+Pigweed provides Doxygen aliases for creating Sphinx cross references within
+Doxygen comments. These should be used when referring to other symbols, such as
+functions, classes, or macros.
+
+.. inclusive-language: disable
+
+The basic alias is ``@crossref``, which supports any `Sphinx domain
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html>`_.
+For readability, aliases for commonnly used types are provided.
+
+.. inclusive-language: enable
+
+- ``@crossref{domain,type,identifier}`` Inserts a cross reference of any type in
+  any Sphinx domain. For example, ``@crossref{c,func,foo}`` is equivalent to
+  ``:c:func:`foo``` and links to the documentation for the C function ``foo``,
+  if it exists.
+- ``@c_macro{identifier}`` Equivalent to ``:c:macro:`identifier```.
+- ``@cpp_func{identifier}`` Equivalent to ``:cpp:func:`identifier```.
+- ``@cpp_class{identifier}`` Equivalent to ``:cpp:class:`identifier```.
+- ``@cpp_type{identifier}`` Equivalent to ``:cpp:type:`identifier```.
+
+.. note::
+
+   Use the `@` aliases described above for all cross references. Doxygen
+   provides other methods for cross references, but Sphinx cross references
+   offer several advantages:
+
+   - Sphinx cross references work for all identifiers known to Sphinx, including
+     those documented with e.g. ``.. cpp:class::`` or extracted from Python.
+     Doxygen references can only refer to identifiers known to Doxygen.
+   - Sphinx cross references always use consistent formatting. Doxygen cross
+     references sometimes render as plain text instead of code-style monospace,
+     or include ``()`` in macros that shouldn't have them.
+   - Sphinx cross references can refer to symbols that have not yet been
+     documented. They will be formatted correctly and become links once the
+     symbols are documented.
+   - Using Sphinx cross references in Doxygen comments makes cross reference
+     syntax more consistent within Doxygen comments and between RST and
+     Doxygen.
+
+Create cross reference links elsewhere in the document to symbols documented
+with Doxygen using standard Sphinx cross references, such as ``:cpp:class:`` and
+``:cpp:func:``.
+
+.. code-block:: rst
+
+   - :cpp:class:`pw::sync::BinarySemaphore::BinarySemaphore`
+   - :cpp:func:`pw::sync::BinarySemaphore::try_acquire`
+
+.. seealso::
+   - `C++ cross reference link syntax`_
+   - `C cross reference link syntax`_
+   - `Python cross reference link syntax`_
+
 .. _Sphinx: https://www.sphinx-doc.org/
 
 .. inclusive-language: disable