RPCS3/llvm
1
0
Fork 0
mirror of https://github.com/RPCS3/llvm.git synced 2025-01-22 10:16:43 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Make the coding standards a bit more clear that we prefer the fancy new

Browse Source 
auto-brief format for doxygen comments. Most notable is switching to
that in the example doxygen comment. I've also tweaked the wording but
am happy to tweak it further if others have suggestions here.

Mostly doing this to capture something I and others have been writing
consistently and repeatedly in code reviews.

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@280419 91177308-0d34-0410-b5e6-96231b3b80d8
This commit is contained in:
Chandler Carruth 2016-09-01 22:18:25 +00:00
parent 5cf52dab7b
commit 2c8b23f86f
1 changed files with 5 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
docs/CodingStandards.rst
View File

@ -267,7 +267,7 @@ code can be distributed under and should not be modified in any way.
The main body is a ``doxygen`` comment (identified by the ``///`` comment
marker instead of the usual ``//``) describing the purpose of the file. The
first sentence or a passage beginning with ``\brief`` is used as an abstract.
first sentence (or a passage beginning with ``\brief``) is used as an abstract.
Any additional information should be separated by a blank line. If an
algorithm is being implemented or something tricky is going on, a reference
to the paper where it is published should be included, as well as any notes or
@ -322,8 +322,9 @@ comment.
Include descriptive paragraphs for all public interfaces (public classes,
member and non-member functions). Don't just restate the information that can
be inferred from the API name. The first sentence or a paragraph beginning
with ``\brief`` is used as an abstract. Put detailed discussion into separate
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.
To refer to parameter names inside a paragraph, use the ``\p name`` command.
@ -351,7 +352,7 @@ A documentation comment that uses all Doxygen features in a preferred way:
.. code-block:: c++
/// \brief Does foo and bar.
/// Does foo and bar.
///
/// Does not do foo the usual way if \p Baz is true.
///