Add examples to clang-format configuration

[sylvestre.ledru]

If you think it makes sense, I will do that for the rest of the options

[klimek]

docs/ClangFormatStyleOptions.rst

218

Do we really align these 3 spaces out?

461

Don't we align the : further to the right?

532

I thought we don't do that for single lines?

747

Missing the space?

[sylvestre.ledru]

docs/ClangFormatStyleOptions.rst

218

nope, bad copy and paste it seems. Sorry

461

Yes, sorry, issue during the copy and paste :(

532

Yes and no. I reported this bug:
https://bugs.llvm.org//show_bug.cgi?id=32117
I will update the example to avoid the confusion

[sylvestre.ledru]

With the rst generation

[djasper]

Hm. I don't actually know whether these examples are useful as is. You only present one setting of the value in most cases. What's interesting is actually how the flag changes the behavior. I mean in most cases, this can be derived from the example, but in those cases, it's also fairly obvious what the flag does. Unfortunately, I also don't have a significantly better idea. Maybe something like https://clangformat.com/ is just better at handling this?

include/clang/Format/Format.h

682

"update" seems like the wrong word. Maybe "affected"?

[sylvestre.ledru]

I see a lot of values in examples. If I started this review, it is because I was lost in all the options and could not find what I was looking for.

If you want, I can update the example to provide results with and without the option.

like

With SpacesInCStyleCastParentheses: true:
x = ( int32 )y
With false:
x = (int32)y

[djasper]

Sure, then go ahead. If these examples would have helped you, that's one datapoint :).

As for presenting the difference in options, that would be useful I think. So if you are up to also doing that, that'd be appreciated.
For bool options it seems easiest to do something like:

true:  x = ( int32 )y;
false: x = (int32)y;

(I'd try to keep this as compact as possible for now as the style page getting much longer also hurts discoverability)

[kimgr]

For what it's worth, I also find this useful to be able to see at a glance what the setting does. I know I've tried several different settings in the past before finding the one I was looking for.

[sylvestre.ledru]

For bool options it seems easiest to do something like:
true: x = ( int32 )y;
false: x = (int32)y;

That works for single declarations but for stuff like:

SomeClass::Constructor()
        : a(a)
        , b(b)
        , c(c) {}

I won't be great :/

[djasper]

I agree, just generally we should aim for keeping these short.

The example you gave might actually be reasonable to compare in two columns, i.e.:

true:                                  false:
SomeClass::Constructor()      vs.      SomeClass::Constructor() : a(a),
        : a(a)                                                    b(b),
        , b(b)                                                    c(c) {}
        , c(c) {}

or some such.

[krasimir]

I also think that examples for the flags are good. My use case is that while developing/debugging its nice to see a short example for a random flag in the documentation pop-up.

[sylvestre.ledru]

With the changes requested by Daniel. This is much better indeed!

[sylvestre.ledru]

updated => affected
+ align the vs

[sylvestre.ledru]

Daniel, it is good for me now.
Once it is accepted, I will work on the rest in a separate commit if that is ok with you;

[djasper]

Looks good. Thank you for doing this!

docs/ClangFormatStyleOptions.rst

   If ``true``, aligns escaped newlines as far left as possible.
   Otherwise puts them into the right-most column.
 
+  .. code-block:: c++
+
+    true:
+    #define A   \
+      int aaaa; \
+      int b;    \
+      int dddddddddd;
+
+    false:
+    #define A                                                                      \
+      int aaaa;                                                                    \
+      int b;                                                                       \
+      int dddddddddd;
+
 **AlignOperands** (``bool``)
   If ``true``, horizontally align operands of binary and ternary
   expressions.

 **AlignTrailingComments** (``bool``)
   If ``true``, aligns trailing comments.
 
+  .. code-block:: c++
+
+    true:                                   false:
+    int a;     // My comment a      vs.     int a; // My comment a
+    int b = 2; // comment  b                int b = 2; // comment about b
+
 **AllowAllParametersOfDeclarationOnNextLine** (``bool``)
   Allow putting all parameters of a function declaration onto
   the next line even if ``BinPackParameters`` is ``false``.

 **AllowShortCaseLabelsOnASingleLine** (``bool``)
   If ``true``, short case labels will be contracted to a single line.
 
+  .. code-block:: c++
+
+    true:                                   false:
+    switch (a) {                    vs.     switch (a) {
+    case 1: x = 1; break;                   case 1:
+    case 2: return;                           x = 1;
+    }                                         break;
+                                            case 2:
+                                              return;
+                                            }
+
 **AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``)
   Dependent on the value, ``int f() { return 0; }`` can be put on a
   single line.

   the string at that point leads to it being indented
   ``ContinuationIndentWidth`` spaces from the start of the line.
 
+  .. code-block:: c++
+
+     true:                                  false:
+     aaaa =                         vs.     aaaa = "bbbb"
+         "bbbb"                                    "cccc";
+         "cccc";
+
 **AlwaysBreakTemplateDeclarations** (``bool``)
   If ``true``, always break after the ``template<...>`` of a template
   declaration.
 
+  .. code-block:: c++
+
+     true:                                  false:
+     template <typename T>          vs.     template <typename T> class C {};
+     class C {};
+
 **BinPackArguments** (``bool``)
   If ``false``, a function call's arguments will either be all on the
   same line or will have one line each.

   Always break constructor initializers before commas and align
   the commas with the colon.
 
+  .. code-block:: c++
+
+     true:                                  false:
+     SomeClass::Constructor()       vs.     SomeClass::Constructor() : a(a),
+         : a(a)                                                   b(b),
+         , b(b)                                                   c(c) {}
+         , c(c) {}
+
 **BreakStringLiterals** (``bool``)
   Allow breaking string literals when formatting.
 

   If ``true``, clang-format adds missing namespace end comments and
   fixes invalid existing ones.
 
+  .. code-block:: c++
+
+     true:                                  false:
+     namespace a {                  vs.     namespace a {
+     foo();                                 foo();
+     } // namespace a;                      }
+
 **ForEachMacros** (``std::vector<std::string>``)
   A vector of macros that should be interpreted as foreach loops
   instead of as function calls.

 **SpaceAfterTemplateKeyword** (``bool``)
   If ``true``, a space will be inserted after the 'template' keyword.
 
+  .. code-block:: c++
+
+     true:                                  false:
+     template <int> void foo();     vs.     template<int> void foo();
+
 **SpaceBeforeAssignmentOperators** (``bool``)
   If ``false``, spaces will be removed before assignment operators.
 
+  .. code-block:: c++
+
+     true:                                  false:
+     int a = 5;                     vs.     int a=5;
+     a += 42                                a+=42;
+
 **SpaceBeforeParens** (``SpaceBeforeParensOptions``)
   Defines in which cases to put a space before opening parentheses.
 

   If ``true``, spaces will be inserted after ``<`` and before ``>``
   in template argument lists.
 
+  .. code-block:: c++
+
+     true:                                  false:
+     static_cast< int >(arg);       vs.     static_cast<int>(arg);
+     std::function< void(int) > fct;        std::function<void(int)> fct;
+
 **SpacesInCStyleCastParentheses** (``bool``)
   If ``true``, spaces may be inserted into C style casts.
 
+  .. code-block:: c++
+
+     true:                                  false:
+     x = ( int32 )y                 vs.     x = (int32)y
+
 **SpacesInContainerLiterals** (``bool``)
   If ``true``, spaces are inserted inside container literals (e.g.
   ObjC and Javascript array and dict literals).

 **SpacesInParentheses** (``bool``)
   If ``true``, spaces will be inserted after ``(`` and before ``)``.
 
+  .. code-block:: c++
+
+     true:                                  false:
+     t f( Deleted & ) & = delete;   vs.     t f(Deleted &) & = delete;
+
 **SpacesInSquareBrackets** (``bool``)
   If ``true``, spaces will be inserted after ``[`` and before ``]``.
+  Lambdas or unspecified size array declarations will not be affected.
 
+  .. code-block:: c++
+
+     true:                                  false:
+     int a[ 5 ];                    vs.     int a[5];
+     std::unique_ptr<int[]> foo() {} // Won't be affected
+
 **Standard** (``LanguageStandard``)
   Format compatible with this standard, e.g. use ``A<A<int> >``
   instead of ``A<A<int>>`` for ``LS_Cpp03``.

include/clang/Format/Format.h

 
   /// \brief If ``true``, aligns escaped newlines as far left as possible.
   /// Otherwise puts them into the right-most column.
+  /// \code
+  ///   true:
+  ///   #define A   \
+  ///     int aaaa; \
+  ///     int b;    \
+  ///     int dddddddddd;
+  ///
+  ///   false:
+  ///   #define A                                                                      \
+  ///     int aaaa;                                                                    \
+  ///     int b;                                                                       \
+  ///     int dddddddddd;
+  /// \endcode
   bool AlignEscapedNewlinesLeft;
 
   /// \brief If ``true``, horizontally align operands of binary and ternary

   bool AlignOperands;
 
   /// \brief If ``true``, aligns trailing comments.
+  /// \code
+  ///   true:                                   false:
+  ///   int a;     // My comment a      vs.     int a; // My comment a
+  ///   int b = 2; // comment  b                int b = 2; // comment about b
+  /// \endcode
   bool AlignTrailingComments;
 
   /// \brief Allow putting all parameters of a function declaration onto

   bool AllowShortBlocksOnASingleLine;
 
   /// \brief If ``true``, short case labels will be contracted to a single line.
+  /// \code
+  ///   true:                                   false:
+  ///   switch (a) {                    vs.     switch (a) {
+  ///   case 1: x = 1; break;                   case 1:
+  ///   case 2: return;                           x = 1;
+  ///   }                                         break;
+  ///                                           case 2:
+  ///                                             return;
+  ///                                           }
+  /// \endcode
   bool AllowShortCaseLabelsOnASingleLine;
 
   /// \brief Different styles for merging short functions containing at most one

   /// in a file look more consistent. Thus, it will only take effect if wrapping
   /// the string at that point leads to it being indented
   /// ``ContinuationIndentWidth`` spaces from the start of the line.
+  /// \code
+  ///    true:                                  false:
+  ///    aaaa =                         vs.     aaaa = "bbbb"
+  ///        "bbbb"                                    "cccc";
+  ///        "cccc";
+  /// \endcode
   bool AlwaysBreakBeforeMultilineStrings;
 
   /// \brief If ``true``, always break after the ``template<...>`` of a template
   /// declaration.
+  /// \code
+  ///    true:                                  false:
+  ///    template <typename T>          vs.     template <typename T> class C {};
+  ///    class C {};
+  /// \endcode
   bool AlwaysBreakTemplateDeclarations;
 
   /// \brief If ``false``, a function call's arguments will either be all on the

 
   /// \brief Always break constructor initializers before commas and align
   /// the commas with the colon.
+  /// \code
+  ///    true:                                  false:
+  ///    SomeClass::Constructor()       vs.     SomeClass::Constructor() : a(a),
+  ///        : a(a)                                                   b(b),
+  ///        , b(b)                                                   c(c) {}
+  ///        , c(c) {}
+  /// \endcode
   bool BreakConstructorInitializersBeforeComma;
 
   /// \brief Break after each annotation on a field in Java files.

 
   /// \brief If ``true``, clang-format adds missing namespace end comments and
   /// fixes invalid existing ones.
+  /// \code
+  ///    true:                                  false:
+  ///    namespace a {                  vs.     namespace a {
+  ///    foo();                                 foo();
+  ///    } // namespace a;                      }
+  /// \endcode
   bool FixNamespaceComments;
 
   /// \brief A vector of macros that should be interpreted as foreach loops

   bool SpaceAfterCStyleCast;
 
   /// \brief If \c true, a space will be inserted after the 'template' keyword.
+  /// \code
+  ///    true:                                  false:
+  ///    template <int> void foo();     vs.     template<int> void foo();
+  /// \endcode
   bool SpaceAfterTemplateKeyword;
 
   /// \brief If ``false``, spaces will be removed before assignment operators.
+  /// \code
+  ///    true:                                  false:
+  ///    int a = 5;                     vs.     int a=5;
+  ///    a += 42                                a+=42;
+  /// \endcode
   bool SpaceBeforeAssignmentOperators;
 
   /// \brief Different ways to put a space before opening parentheses.

 
   /// \brief If ``true``, spaces will be inserted after ``<`` and before ``>``
   /// in template argument lists.
+  /// \code
+  ///    true:                                  false:
+  ///    static_cast< int >(arg);       vs.     static_cast<int>(arg);
+  ///    std::function< void(int) > fct;        std::function<void(int)> fct;
+  /// \endcode
   bool SpacesInAngles;
 
   /// \brief If ``true``, spaces are inserted inside container literals (e.g.

   bool SpacesInContainerLiterals;
 
   /// \brief If ``true``, spaces may be inserted into C style casts.
+  /// \code
+  ///    true:                                  false:
+  ///    x = ( int32 )y                 vs.     x = (int32)y
+  /// \endcode
   bool SpacesInCStyleCastParentheses;
 
   /// \brief If ``true``, spaces will be inserted after ``(`` and before ``)``.
+  /// \code
+  ///    true:                                  false:
+  ///    t f( Deleted & ) & = delete;   vs.     t f(Deleted &) & = delete;
+  /// \endcode
   bool SpacesInParentheses;
 
   /// \brief If ``true``, spaces will be inserted after ``[`` and before ``]``.
+  /// Lambdas or unspecified size array declarations will not be affected.
+  /// \code
+  ///    true:                                  false:
+  ///    int a[ 5 ];                    vs.     int a[5];
+  ///    std::unique_ptr<int[]> foo() {} // Won't be affected
+  /// \endcode
   bool SpacesInSquareBrackets;
 
   /// \brief Supported language standards.