Add more examples to clang-format configuration

[sylvestre.ledru]

docs/ClangFormatStyleOptions.rst

671

Is this example valid? I don't see why clang-format formats this this way?

686

Same

BasedOnStyle: LLVM
BreakBeforeBinaryOperators: All

[sylvestre.ledru]

More example (JS)

[sylvestre.ledru]

Improve consistency on an example

[sylvestre.ledru]

Daniel, is that ok with you?

[djasper]

Looks good, just minor remarks.

include/clang/Format/Format.h

974

I'd contract these to a single line.

1007

nit: The indent on the right is incorrect (i.e. should not be different).

docs/ClangFormatStyleOptions.rst

 
 **AlwaysBreakAfterDefinitionReturnType** (``DefinitionReturnTypeBreakingStyle``)
   The function definition return type breaking style to use.  This
-  option is deprecated and is retained for backwards compatibility.
+  option is **deprecated** and is retained for backwards compatibility.
 
   Possible values:
 

   If ``false``, a function call's arguments will either be all on the
   same line or will have one line each.
 
+  .. code-block:: c++
+
+    true:
+    void f() {
+      f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa,
+        aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
+    }
+
+    false:
+    void f() {
+      f(aaaaaaaaaaaaaaaaaaaa,
+        aaaaaaaaaaaaaaaaaaaa,
+        aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
+    }
+
 **BinPackParameters** (``bool``)
   If ``false``, a function declaration's or function definition's
   parameters will either all be on the same line or will have one line each.
 
+  .. code-block:: c++
+
+    true:
+    void f(int aaaaaaaaaaaaaaaaaaaa, int aaaaaaaaaaaaaaaaaaaa,
+           int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
+
+    false:
+    void f(int aaaaaaaaaaaaaaaaaaaa,
+           int aaaaaaaaaaaaaaaaaaaa,
+           int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
+
 **BraceWrapping** (``BraceWrappingFlags``)
   Control of individual brace wrapping cases.
 

   * ``BOS_None`` (in configuration: ``None``)
     Break after operators.
 
+    .. code-block:: c++
+
+       LooooooooooongType loooooooooooooooooooooongVariable =
+           someLooooooooooooooooongFunction();
+
+       bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +
+                            aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa ==
+                        aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa &&
+                    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa >
+                        ccccccccccccccccccccccccccccccccccccccccc;
+
   * ``BOS_NonAssignment`` (in configuration: ``NonAssignment``)
     Break before operators that aren't assignments.
 
+    .. code-block:: c++
+
+       LooooooooooongType loooooooooooooooooooooongVariable =
+           someLooooooooooooooooongFunction();
+
+       bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+                            + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+                        == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+                    && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+                           > ccccccccccccccccccccccccccccccccccccccccc;
+
   * ``BOS_All`` (in configuration: ``All``)
     Break before operators.
 
+    .. code-block:: c++
 
+       LooooooooooongType loooooooooooooooooooooongVariable
+           = someLooooooooooooooooongFunction();
 
+       bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+                            + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+                        == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+                    && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+                           > ccccccccccccccccccccccccccccccccccccccccc;
+
+
+
 **BreakBeforeBraces** (``BraceBreakingStyle``)
   The brace breaking style to use.
 

   A regular expression that describes comments with special meaning,
   which should not be split into lines or otherwise changed.
 
+  .. code-block:: c++
+
+     CommentPragmas: '^ FOOBAR pragma:'
+     // Will leave the following line unaffected
+     #include <vector> // FOOBAR pragma: keep
+
 **ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``)
   If the constructor initializers don't fit on a line, put each
   initializer on its own line.

 **IndentWidth** (``unsigned``)
   The number of columns to use for indentation.
 
+  .. code-block:: c++
+
+     IndentWidth: 3
+     void f() {
+        someFunction();
+        if (true, false) {
+           f();
+        }
+     }
+
 **IndentWrappedFunctionNames** (``bool``)
   Indent if a function definition or declaration is wrapped after the
   type.

   * ``JSQS_Leave`` (in configuration: ``Leave``)
     Leave string quotes as they are.
 
+    .. code-block:: js
+
+       string1 = "foo";
+       string2 = 'bar';
+
   * ``JSQS_Single`` (in configuration: ``Single``)
     Always use single quotes.
 
+    .. code-block:: js
+
+       string1 = 'foo';
+       string2 = 'bar';
+
   * ``JSQS_Double`` (in configuration: ``Double``)
     Always use double quotes.
 
+    .. code-block:: js
 
+       string1 = "foo";
+       string2 = "bar";
 
+
+
 **JavaScriptWrapImports** (``bool``)
   Whether to wrap JavaScript import/export statements.
 
+  .. code-block:: js
+
+     true:
+     import {
+         VeryLongImportsAreAnnoying,
+         VeryLongImportsAreAnnoying,
+         VeryLongImportsAreAnnoying,
+     } from 'some/module.js'
+
+     false:
+     import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js"
+
 **KeepEmptyLinesAtTheStartOfBlocks** (``bool``)
   If true, empty lines at the start of blocks are kept.
 

 **MacroBlockBegin** (``std::string``)
   A regular expression matching macros that start a block.
 
+  .. code-block:: c++
+
+     # With:
+     MacroBlockBegin: "^\
+     NS_MAP_BEGIN|\
+     NS_TABLE_HEAD$"
+     MacroBlockEnd: "^\
+     NS_MAP_END|\
+     NS_TABLE_.*_END$"
+
+     NS_MAP_BEGIN
+       foo();
+     NS_MAP_END
+
+     NS_TABLE_HEAD
+       bar();
+     NS_TABLE_FOO_END
+
+     # Without:
+     NS_MAP_BEGIN
+     foo();
+     NS_MAP_END
+
+     NS_TABLE_HEAD
+     bar();
+     NS_TABLE_FOO_END
+
 **MacroBlockEnd** (``std::string``)
   A regular expression matching macros that end a block.
 

 **MaxEmptyLinesToKeep** (``unsigned``)
   The maximum number of consecutive empty lines to keep.
 
+  .. code-block:: c++
+
+     MaxEmptyLinesToKeep: 1         vs.     MaxEmptyLinesToKeep: 1
+     int f() {                              int f() {
+     int = 1;                                   int i = 1;
+                                                i = foo();
+       i = foo();                               return i;
+                                            }
+       return i;
+     }
+
 **NamespaceIndentation** (``NamespaceIndentationKind``)
   The indentation used for namespaces.
 

   * ``NI_None`` (in configuration: ``None``)
     Don't indent in namespaces.
 
+    .. code-block:: c++
+
+       namespace out {
+       int i;
+       namespace in {
+       int i;
+       }
+       }
+
   * ``NI_Inner`` (in configuration: ``Inner``)
     Indent only in inner namespaces (nested in other namespaces).
 
+    .. code-block:: c++
+
+       namespace out {
+       int i;
+       namespace in {
+         int i;
+       }
+       }
+
   * ``NI_All`` (in configuration: ``All``)
     Indent in all namespaces.
 
+    .. code-block:: c++
 
+       namespace out {
+         int i;
+         namespace in {
+           int i;
+         }
+       }
 
+
+
 **ObjCBlockIndentWidth** (``unsigned``)
   The number of characters to use for indentation of ObjC blocks.
 

 **ReflowComments** (``bool``)
   If ``true``, clang-format will attempt to re-flow comments.
 
+  .. code-block:: c++
+
+     false:
+     // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
+     /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
+
+     true:
+     // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
+     // information
+     /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
+      * information */
+
 **SortIncludes** (``bool``)
   If ``true``, clang-format will sort ``#includes``.
 

   * ``SBPO_Never`` (in configuration: ``Never``)
     Never put a space before opening parentheses.
 
+    .. code-block:: c++
+
+       void f() {
+         if(true) {
+           f();
+         }
+       }
+
   * ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``)
     Put a space before opening parentheses only after control statement
     keywords (``for/if/while...``).
 
+    .. code-block:: c++
+
+       void f() {
+         if (true) {
+           f();
+         }
+       }
+
   * ``SBPO_Always`` (in configuration: ``Always``)
     Always put a space before opening parentheses, except when it's
     prohibited by the syntax rules (in function-like macro definitions) or

     when determined by other style rules (after unary operators, opening
     parentheses, etc.)
 
+    .. code-block:: c++
 
+       void f () {
+         if (true) {
+           f ();
+         }
+       }
 
+
+
 **SpaceInEmptyParentheses** (``bool``)
   If ``true``, spaces may be inserted into ``()``.
 
+  .. code-block:: c++
+
+     true:
+     void f( ) {
+       int x[] = {foo( ), bar( )};
+       if (true) {
+         f( );
+       }
+     }
+
+     false:
+     void f() {
+       int x[] = {foo(), bar()};
+       if (true) {
+         f();
+       }
+     }
+
 **SpacesBeforeTrailingComments** (``unsigned``)
   The number of spaces before trailing line comments
   (``//`` - comments).

   those commonly have different usage patterns and a number of special
   cases.
 
+  .. code-block:: c++
+
+     SpacesBeforeTrailingComments: 3
+     void f() {
+       if (true) {   // foo1
+         f();        // bar
+       }             // foo
+     }
+
 **SpacesInAngles** (``bool``)
   If ``true``, spaces will be inserted after ``<`` and before ``>``
   in template argument lists.

   If ``true``, spaces are inserted inside container literals (e.g.
   ObjC and Javascript array and dict literals).
 
+  .. code-block:: js
+
+     true:                                  false:
+     var arr = [ 1, 2, 3 ];         vs.     var arr = [1, 2, 3];
+     f({a : 1, b : 2, c : 3});              f({a: 1, b: 2, c: 3});
+
 **SpacesInParentheses** (``bool``)
   If ``true``, spaces will be inserted after ``(`` and before ``)``.
 

           r();
       }
   }
-

include/clang/Format/Format.h

   bool AllowShortLoopsOnASingleLine;
 
   /// \brief Different ways to break after the function definition return type.
-  /// This option is deprecated and is retained for backwards compatibility.
+  /// This option is **deprecated** and is retained for backwards compatibility.
   enum DefinitionReturnTypeBreakingStyle {
     /// Break after return type automatically.
     /// ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.

   };
 
   /// \brief The function definition return type breaking style to use.  This
-  /// option is deprecated and is retained for backwards compatibility.
+  /// option is **deprecated** and is retained for backwards compatibility.
   DefinitionReturnTypeBreakingStyle AlwaysBreakAfterDefinitionReturnType;
 
   /// \brief The function declaration return type breaking style to use.

 
   /// \brief If ``false``, a function call's arguments will either be all on the
   /// same line or will have one line each.
+  /// \code
+  ///   true:
+  ///   void f() {
+  ///     f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa,
+  ///       aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
+  ///   }
+  ///
+  ///   false:
+  ///   void f() {
+  ///     f(aaaaaaaaaaaaaaaaaaaa,
+  ///       aaaaaaaaaaaaaaaaaaaa,
+  ///       aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
+  ///   }
+  /// \endcode
   bool BinPackArguments;
 
   /// \brief If ``false``, a function declaration's or function definition's
   /// parameters will either all be on the same line or will have one line each.
+  /// \code
+  ///   true:
+  ///   void f(int aaaaaaaaaaaaaaaaaaaa, int aaaaaaaaaaaaaaaaaaaa,
+  ///          int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
+  ///
+  ///   false:
+  ///   void f(int aaaaaaaaaaaaaaaaaaaa,
+  ///          int aaaaaaaaaaaaaaaaaaaa,
+  ///          int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
+  /// \endcode
   bool BinPackParameters;
 
   /// \brief The style of breaking before or after binary operators.
   enum BinaryOperatorStyle {
     /// Break after operators.
+    /// \code
+    ///    LooooooooooongType loooooooooooooooooooooongVariable =
+    ///        someLooooooooooooooooongFunction();
+    ///
+    ///    bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +
+    ///                         aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa ==
+    ///                     aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa &&
+    ///                 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa >
+    ///                     ccccccccccccccccccccccccccccccccccccccccc;
+    /// \endcode
     BOS_None,
     /// Break before operators that aren't assignments.
+    /// \code
+    ///    LooooooooooongType loooooooooooooooooooooongVariable =
+    ///        someLooooooooooooooooongFunction();
+    ///
+    ///    bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+    ///                         + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+    ///                     == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+    ///                 && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+    ///                        > ccccccccccccccccccccccccccccccccccccccccc;
+    /// \endcode
     BOS_NonAssignment,
     /// Break before operators.
+    /// \code
+    ///    LooooooooooongType loooooooooooooooooooooongVariable
+    ///        = someLooooooooooooooooongFunction();
+    ///
+    ///    bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+    ///                         + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+    ///                     == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+    ///                 && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+    ///                        > ccccccccccccccccccccccccccccccccccccccccc;
+    /// \endcode
     BOS_All,
   };
 

 
   /// \brief A regular expression that describes comments with special meaning,
   /// which should not be split into lines or otherwise changed.
+  /// \code
+  ///    CommentPragmas: '^ FOOBAR pragma:'
+  ///    // Will leave the following line unaffected
+  ///    #include <vector> // FOOBAR pragma: keep
+  /// \endcode
   std::string CommentPragmas;
 
   /// \brief If ``true``, in the class inheritance expression clang-format will

   bool IndentCaseLabels;
 
   /// \brief The number of columns to use for indentation.
+  /// \code
+  ///    IndentWidth: 3
+  ///    void f() {
+  ///       someFunction();
+  ///       if (true, false) {
+  ///          f();
+  ///       }
+  ///    }
+  /// \endcode
   unsigned IndentWidth;
 
   /// \brief Indent if a function definition or declaration is wrapped after the

   /// strings.
   enum JavaScriptQuoteStyle {
     /// Leave string quotes as they are.
+    /// \code{.js}
+    ///    string1 = "foo";
+    ///    string2 = 'bar';
+    /// \endcode
     JSQS_Leave,
     /// Always use single quotes.
+    /// \code{.js}
+    ///    string1 = 'foo';
+    ///    string2 = 'bar';
+    /// \endcode
     JSQS_Single,
     /// Always use double quotes.
+    /// \code{.js}
+    ///    string1 = "foo";
+    ///    string2 = "bar";
+    /// \endcode
     JSQS_Double
   };
 

   JavaScriptQuoteStyle JavaScriptQuotes;
 
   /// \brief Whether to wrap JavaScript import/export statements.
+  /// \code{.js}
+  ///    true:
+  ///    import {
+  ///        VeryLongImportsAreAnnoying,
+  ///        VeryLongImportsAreAnnoying,
+  ///        VeryLongImportsAreAnnoying,
+  ///    } from 'some/module.js'
+  ///
+  ///    false:
+  ///    import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js"
+  /// \endcode
   bool JavaScriptWrapImports;
 
   /// \brief If true, empty lines at the start of blocks are kept.

   LanguageKind Language;
 
   /// \brief A regular expression matching macros that start a block.
+  /// \code
+  ///    # With:
+  ///    MacroBlockBegin: "^\
+  ///    NS_MAP_BEGIN|\
+  ///    NS_TABLE_HEAD$"
+  ///    MacroBlockEnd: "^\
+  ///    NS_MAP_END|\
+  ///    NS_TABLE_.*_END$"
+  ///
+  ///    NS_MAP_BEGIN
+  ///      foo();
+  ///    NS_MAP_END
+  ///
+  ///    NS_TABLE_HEAD
+  ///      bar();
+  ///    NS_TABLE_FOO_END
+  ///
+  ///    # Without:
+  ///    NS_MAP_BEGIN
+  ///    foo();
+  ///    NS_MAP_END
+  ///
+  ///    NS_TABLE_HEAD
+  ///    bar();
+  ///    NS_TABLE_FOO_END
+  /// \endcode
   std::string MacroBlockBegin;
 
   /// \brief A regular expression matching macros that end a block.

   std::string MacroBlockEnd;
 
   /// \brief The maximum number of consecutive empty lines to keep.
+  /// \code
+  ///    MaxEmptyLinesToKeep: 1         vs.     MaxEmptyLinesToKeep: 1
+  ///    int f() {                              int f() {
+  ///    int = 1;                                   int i = 1;
+  ///                                               i = foo();
+  ///      i = foo();                               return i;
+  ///                                           }
+  ///      return i;
+  ///    }
+  /// \endcode
   unsigned MaxEmptyLinesToKeep;
 
   /// \brief Different ways to indent namespace contents.
   enum NamespaceIndentationKind {
     /// Don't indent in namespaces.
+    /// \code
+    ///    namespace out {
+    ///    int i;
+    ///    namespace in {
+    ///    int i;
+    ///    }
+    ///    }
+    /// \endcode
     NI_None,
     /// Indent only in inner namespaces (nested in other namespaces).
+    /// \code
+    ///    namespace out {
+    ///    int i;
+    ///    namespace in {
+    ///      int i;
+    ///    }
+    ///    }
+    /// \endcode
     NI_Inner,
     /// Indent in all namespaces.
+    /// \code
+    ///    namespace out {
+    ///      int i;
+    ///      namespace in {
+    ///        int i;
+    ///      }
+    ///    }
+    /// \endcode
     NI_All
   };
 

   PointerAlignmentStyle PointerAlignment;
 
   /// \brief If ``true``, clang-format will attempt to re-flow comments.
+  /// \code
+  ///    false:
+  ///    // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
+  ///    /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
+  ///
+  ///    true:
+  ///    // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
+  ///    // information
+  ///    /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
+  ///     * information */
+  /// \endcode
   bool ReflowComments;
 
   /// \brief If ``true``, clang-format will sort ``#includes``.

   /// \brief Different ways to put a space before opening parentheses.
   enum SpaceBeforeParensOptions {
     /// Never put a space before opening parentheses.
+    /// \code
+    ///    void f() {
+    ///      if(true) {
+    ///        f();
+    ///      }
+    ///    }
+    /// \endcode
     SBPO_Never,
     /// Put a space before opening parentheses only after control statement
     /// keywords (``for/if/while...``).
+    /// \code
+    ///    void f() {
+    ///      if (true) {
+    ///        f();
+    ///      }
+    ///    }
+    /// \endcode
     SBPO_ControlStatements,
     /// Always put a space before opening parentheses, except when it's
     /// prohibited by the syntax rules (in function-like macro definitions) or
     /// when determined by other style rules (after unary operators, opening
     /// parentheses, etc.)
+    /// \code
+    ///    void f () {
+    ///      if (true) {
+    ///        f ();
+    ///      }
+    ///    }
+    /// \endcode
     SBPO_Always
   };
 

   SpaceBeforeParensOptions SpaceBeforeParens;
 
   /// \brief If ``true``, spaces may be inserted into ``()``.
+  /// \code
+  ///    true:
+  ///    void f( ) {
+  ///      int x[] = {foo( ), bar( )};
+  ///      if (true) {
+  ///        f( );
+  ///      }
+  ///    }
+  ///
+  ///    false:
+  ///    void f() {
+  ///      int x[] = {foo(), bar()};
+  ///      if (true) {
+  ///        f();
+  ///      }
+  ///    }
+  /// \endcode
   bool SpaceInEmptyParentheses;
 
   /// \brief The number of spaces before trailing line comments

   /// This does not affect trailing block comments (``/*`` - comments) as
   /// those commonly have different usage patterns and a number of special
   /// cases.
+  /// \code
+  ///    SpacesBeforeTrailingComments: 3
+  ///    void f() {
+  ///      if (true) {   // foo1
+  ///        f();        // bar
+  ///      }             // foo
+  ///    }
+  /// \endcode
   unsigned SpacesBeforeTrailingComments;
 
   /// \brief If ``true``, spaces will be inserted after ``<`` and before ``>``

 
   /// \brief If ``true``, spaces are inserted inside container literals (e.g.
   /// ObjC and Javascript array and dict literals).
+  /// \code{.js}
+  ///    true:                                  false:
+  ///    var arr = [ 1, 2, 3 ];         vs.     var arr = [1, 2, 3];
+  ///    f({a : 1, b : 2, c : 3});              f({a: 1, b: 2, c: 3});
+  /// \endcode
   bool SpacesInContainerLiterals;
 
   /// \brief If ``true``, spaces may be inserted into C style casts.