[llvm] r280419 - Make the coding standards a bit more clear that we prefer the fancy new

Chandler Carruth via llvm-commits llvm-commits at lists.llvm.org
Thu Sep 1 15:18:25 PDT 2016


Author: chandlerc
Date: Thu Sep  1 17:18:25 2016
New Revision: 280419

URL: http://llvm.org/viewvc/llvm-project?rev=280419&view=rev
Log:
Make the coding standards a bit more clear that we prefer the fancy new
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.

Modified:
    llvm/trunk/docs/CodingStandards.rst

Modified: llvm/trunk/docs/CodingStandards.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/CodingStandards.rst?rev=280419&r1=280418&r2=280419&view=diff
==============================================================================
--- llvm/trunk/docs/CodingStandards.rst (original)
+++ llvm/trunk/docs/CodingStandards.rst Thu Sep  1 17:18:25 2016
@@ -267,7 +267,7 @@ code can be distributed under and should
 
 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 Do
 
 .. code-block:: c++
 
-  /// \brief Does foo and bar.
+  /// Does foo and bar.
   ///
   /// Does not do foo the usual way if \p Baz is true.
   ///




More information about the llvm-commits mailing list