[llvm] r199620 - Add some wording to the coding standards to say how to indent namespaces

[Chandler Carruth]

Author: chandlerc
Date: Sun Jan 19 19:40:43 2014
New Revision: 199620

URL: http://llvm.org/viewvc/llvm-project?rev=199620&view=rev
Log:
Add some wording to the coding standards to say how to indent namespaces
(and to mention namespace ending comments). This is based on a quick
discussion on the developer mailing list where there was essentially no
objections to a simple and consistent rule. This should avoid future
debates about whether or not a namespace is "big enough" to indent. It
also matches clang-format's current behavior with LLVM source code which
hasn't really seen any opposition in code reviews that I spot checked.

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=199620&r1=199619&r2=199620&view=diff
==============================================================================
--- llvm/trunk/docs/CodingStandards.rst (original)
+++ llvm/trunk/docs/CodingStandards.rst Sun Jan 19 19:40:43 2014
@@ -106,6 +106,24 @@ an algorithm is being implemented or som
 to the paper where it is published should be included, as well as any notes or
 *gotchas* in the code to watch out for.
 
+Namespace Markers
+"""""""""""""""""
+
+We don't indent namespaces (see below) and so feel free to add markers to the
+end of a namespace where it helps readabilitily:
+
+.. code-block:: c++
+
+  namespace foo {
+
+  // Lots of code here...
+
+  } // End foo namespace
+
+This isn't required, and in many cases (such as the namespace used for an
+entire file like the 'llvm' namespace in header files) it isn't really useful.
+Use your judgment and add it where it helps.
+
 Class overviews
 """""""""""""""
 
@@ -336,7 +354,33 @@ Indent Code Consistently
 
 Okay, in your first year of programming you were told that indentation is
 important.  If you didn't believe and internalize this then, now is the time.
-Just do it.
+Just do it.  A few cases are called out here that have common alternatives. The
+intent in saying which way to format things is to increase consistency across
+the LLVM codebase.
+
+Namespaces
+""""""""""
+
+A simple rule: don't indent them. Here are examples of well formatted and
+indented namespaces:
+
+.. code-block:: c++
+  namespace llvm {
+
+  namespace foo {
+  class A;
+  class B;
+  }
+
+  namespace {
+  /// \brief Some local class definition.
+  /// ...
+  class Widget {
+    // ... lots of code here ...
+  };
+  } // End anonymous namespace
+
+  } // End llvm namespace
 
 Compiler Issues
 ---------------