Doomhowl-Interactive/llvm-project
0
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

[llvm] Update policy for Doxygen comments in the Coding Standards (#179898)

Browse Source 
This PR updates the policy regarding Doxygen comments in the Coding
Standards based on an RFC discussion on Discourse:

https://discourse.llvm.org/t/rfc-policy-for-doxygen-comments-in-lldb/89675/
This commit is contained in:
Jonas Devlieghere
2026-02-06 09:12:00 +01:00
committed by GitHub
parent a6f026414d
commit 7bef2cdec6
1 changed files with 17 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
llvm/docs/CodingStandards.rst
View File

@@ -278,11 +278,23 @@ Use the ``\file`` command to turn the standard file header into a file-level
comment.
Include descriptive paragraphs for all public interfaces (public classes,
member and non-member functions). Avoid restating the information that can
be inferred from the API name. The first sentence (or a paragraph beginning
with ``\brief``) is used as an abstract. Try to use a single sentence as the
``\brief`` adds visual clutter. Put detailed discussion into separate
paragraphs.
member and non-member functions). Avoid restating the information that can be
inferred from the API name or signature. The first sentence (or a paragraph
beginning with ``\brief``) is used as an abstract. Try to use a single
sentence as the ``\brief`` adds visual clutter. Put detailed discussion into
separate paragraphs.
A minimal documentation comment:
.. code-block:: c++
/// Sets the xyzzy property to \p Baz.
void setXyzzy(bool Baz);
Only include code examples, function parameters and return values when it
provides additional information, such as intent, usage, or behavior that’s
non-obvious. Use descriptive function and argument names to
eliminate the need for documentation comments when possible.
To refer to parameter names inside a paragraph, use the ``\p name`` command.
Don't use the ``\arg name`` command since it starts a new paragraph that
@@ -298,13 +310,6 @@ respectively.
To describe function return value, start a new paragraph with the ``\returns``
command.
A minimal documentation comment:
.. code-block:: c++
/// Sets the xyzzy property to \p Baz.
void setXyzzy(bool Baz);
A documentation comment that uses all Doxygen features in a preferred way:
.. code-block:: c++