Lines Matching full:doxygen

1 .. _docs-style-doxygen:
4 Doxygen style guide
6 .. _Doxygen: https://www.doxygen.nl/index.html
8 ``pigweed.dev`` uses `Doxygen`_ to auto-generate C and C++ API references
10 called **Doxygen comments**. This style guide shows you how to format Doxygen
13 .. _docs-style-doxygen-quickstart:
32 #. Annotate your header file using `Doxygen`_ syntax. All of the comments
33    that start with triple slashes (``///``) are Doxygen comments. Doxygen
39    `Breathe directives`_. Breathe is the bridge between Doxygen and `Sphinx`_,
41    :ref:`docs-style-doxygen-breathe-overview` for more explanation.
51 .. _docs-style-doxygen-writing:
60 .. _docs-style-doxygen-comment-style:
63 Doxygen comment style
66 that Doxygen converts into API references.
68 .. _docs-style-doxygen-comment-syntax:
82 .. _docs-style-doxygen-special-command-syntax:
86 .. _Special commands: https://www.doxygen.nl/manual/commands.html
89 tools of Doxygen. Doxygen recognizes words that begin with either backslashes
107 .. _docs-style-doxygen-structural-commands:
111 .. _Doxygen structural commands: https://doxygen.nl/manual/docblocks.html#structuralcommands
113 `Doxygen structural commands`_ like ``@struct``, ``@fn``, ``@class``, and ``@file``
115 needed. In other words, if your Doxygen comment renders correctly without the
146 .. _docs-style-doxygen-params:
189 .. _docs-style-doxygen-pre:
215 .. _docs-style-doxygen-pw_status:
231 Doxygen converts this alias into a link to the status code's reference
283   because it's a reStructuredText directive and Doxygen doesn't natively
323 .. _docs-style-doxygen-namespaces:
337 .. _docs-style-doxygen-multisymbol:
354 .. _docs-style-doxygen-xrefs:
359 .. _docs-style-doxygen-xrefs-comments:
361 X-refs in Doxygen comments
384 Avoid Doxygen x-refs
388 Doxygen provides its own features for x-refs but they should be avoided
393   Python. Doxygen references can only refer to identifiers known to Doxygen.
394 * Sphinx x-refs always use consistent formatting. Doxygen
401 Using Sphinx x-refs in Doxygen comments makes x-ref syntax more consistent
402 within Doxygen comments and between reStructuredText and Doxygen.
404 .. _docs-style-doxygen-xrefs-rest:
406 Cross-references in reST to Doxygen symbols
408 After you've used Doxygen to generate API references, you can link to those
435 .. _docs-style-doxygen-embedded-rest:
439 To use reStructuredText (reST) within a Doxygen comment, wrap the reST
442 .. _docs-style-doxygen-breathe:
452 .. _docs-style-doxygen-breathe-overview:
463 After you annotate your header comments as Doxygen comments, you need to
467 you surface the API reference on ``pigweed.dev``. Doxygen doesn't natively
470 and Doxygen to work together.
472 .. _docs-style-doxygen-breathe-doxygenclass:
515 .. _docs-style-doxygen-breathe-doxygenfunction:
530 .. _docs-style-doxygen-breathe-doxygendefine:
545 .. _docs-style-doxygen-breathe-doxygengroup:
555 :ref:`docs-style-doxygen-breathe-doxygenclass`-based organization
558 .. _@defgroup: https://www.doxygen.nl/manual/commands.html#cmddefgroup
559 .. _@addtogroup: https://www.doxygen.nl/manual/commands.html#cmdaddtogroup
560 .. _@ingroup: https://www.doxygen.nl/manual/commands.html#cmdingroup
562 To create a group, annotate your Doxygen comments with `@defgroup`_,
592 .. _docs-style-doxygen-breathe-doxygentypedef:
607 .. _docs-style-doxygen-breathe-doxygenfile:
613 Don't use `doxygenfile`_. Use :ref:`docs-style-doxygen-breathe-doxygengroup`
616 .. _docs-style-doxygen-disabled-include:
625 Doxygen and Breathe have the ability to auto-generate ``#include`` statements