Add more examples to clang-format configuration

[Eugene.Zelenko]

docs/ClangFormatStyleOptions.rst

644

Shouldn't it be java?

1293

Shouldn't it be objective-c?

[sylvestre.ledru]

Thanks, indeed! :)

[sylvestre.ledru]

Daniel, wdyt? :)

[djasper]

Generally please upload diffs with more contexts. For some here it's not even clear to which option they refer ;)

docs/ClangFormatStyleOptions.rst

941

You could force line wraps with tailing //-comments instead.

978

I think this example is very confusing. Possibly for this option, it doesn't really makes sense to give examples. Or don't have a before/after but instead have two examples where clang-format determines different pointer alignment?

[sylvestre.ledru]

docs/ClangFormatStyleOptions.rst

941

much better. thanks

978

right, removed.
I updated the wording of the desc

[sylvestre.ledru]

Daniel, is that ok with you?

[djasper]

Yes, thank you!

docs/ClangFormatStyleOptions.rst

 **BreakAfterJavaFieldAnnotations** (``bool``)
   Break after each annotation on a field in Java files.
 
+  .. code-block:: c++
+
+     true:                                  false:
+     @Partial                       vs.     @Partial @Mock DataLoad loader;
+     @Mock
+     DataLoad loader;
+
 **BreakBeforeBinaryOperators** (``BinaryOperatorStyle``)
   The way to wrap binary operators.
 

 **ContinuationIndentWidth** (``unsigned``)
   Indent width for line continuations.
 
+  .. code-block:: c++
+
+     ContinuationIndentWidth: 2
+     ColumnLimit: 15
+
+     int i =
+       longFunction(
+         arg);
+
 **Cpp11BracedListStyle** (``bool``)
   If ``true``, format braced lists as best suited for C++11 braced
   lists.

   the parentheses of a function call with that name. If there is no name,
   a zero-length name is assumed.
 
+  .. code-block:: c++
+
+     true:                                  false:
+     vector<int> x{1, 2, 3, 4};     vs.     vector<int> x{ 1, 2, 3, 4 };
+     vector<T> x{{}, {}, {}, {}};           vector<T> x{ {}, {}, {}, {} };
+     f(MyMap[{composite, key}]);            f(MyMap[{ composite, key }]);
+     new int[3]{1, 2, 3};                   new int[3]{ 1, 2, 3 };
+
 **DerivePointerAlignment** (``bool``)
   If ``true``, analyze the formatted file for the most common
   alignment of ``&`` and ``*``. ``PointerAlignment`` is then used only as
   fallback.
 
+  .. code-block:: c++
+
+     original:                      vs.     true:
+     int *foo = 2;                          int *foo = 2;
+     int &j = i;                            int &j = i;
+     int *k = & j;                          int *k = &j;
+     T* k = &j;                             T *k = &j;
+
 **DisableFormat** (``bool``)
   Disables formatting completely.
 

   When ``false``, use the same indentation level as for the switch statement.
   Switch statement body is always indented one level more than case labels.
 
+  .. code-block:: c++
+
+     false:                                 true:
+     switch (fool) {                vs.     switch (fool) {
+     case 1:                                  case 1:
+       bar();                                   bar();
+       break;                                   break;
+     default:                                 default:
+       plop();                                  plop();
+     }                                      }
+
 **IndentWidth** (``unsigned``)
   The number of columns to use for indentation.
 

   .. code-block:: c++
 
      IndentWidth: 3
+
      void f() {
         someFunction();
         if (true, false) {

   Indent if a function definition or declaration is wrapped after the
   type.
 
+  .. code-block:: c++
+
+     true:
+     LoooooooooooooooooooooooooooooooooooooooongReturnType
+         LoooooooooooooooooooooooooooooooongFunctionDeclaration();
+
+     false:
+     LoooooooooooooooooooooooooooooooooooooooongReturnType
+     LoooooooooooooooooooooooooooooooongFunctionDeclaration();
+
 **JavaScriptQuotes** (``JavaScriptQuoteStyle``)
   The JavaScriptQuoteStyle to use for JavaScript strings.
 

      import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js"
 
 **KeepEmptyLinesAtTheStartOfBlocks** (``bool``)
-  If true, empty lines at the start of blocks are kept.
+  If true, the empty line at the start of blocks is kept.
 
+  .. code-block:: c++
+
+     true:                                  false:
+     if (foo) {                     vs.     if (foo) {
+                                              bar();
+       bar();                               }
+     }
+
 **Language** (``LanguageKind``)
   Language, this format style is targeted at.
 

 **ObjCBlockIndentWidth** (``unsigned``)
   The number of characters to use for indentation of ObjC blocks.
 
+  .. code-block:: c++
+
+     ObjCBlockIndentWidth: 4
+
+     [operation setCompletionBlock:^{
+         [self onOperationDone];
+     }];
+
 **ObjCSpaceAfterProperty** (``bool``)
   Add a space after ``@property`` in Objective-C, i.e. use
   ``@property (readonly)`` instead of ``@property(readonly)``.

include/clang/Format/Format.h

   bool BreakConstructorInitializersBeforeComma;
 
   /// \brief Break after each annotation on a field in Java files.
+  /// \code
+  ///    true:                                  false:
+  ///    @Partial                       vs.     @Partial @Mock DataLoad loader;
+  ///    @Mock
+  ///    DataLoad loader;
+  /// \endcode
   bool BreakAfterJavaFieldAnnotations;
 
   /// \brief Allow breaking string literals when formatting.

   unsigned ConstructorInitializerIndentWidth;
 
   /// \brief Indent width for line continuations.
+  /// \code
+  ///    ContinuationIndentWidth: 2
+  ///    ColumnLimit: 15
+  ///
+  ///    int i =
+  ///      longFunction(
+  ///        arg);
+  /// \endcode
   unsigned ContinuationIndentWidth;
 
   /// \brief If ``true``, format braced lists as best suited for C++11 braced

   /// (e.g. a type or variable name), clang-format formats as if the ``{}`` were
   /// the parentheses of a function call with that name. If there is no name,
   /// a zero-length name is assumed.
+  /// \code
+  ///    true:                                  false:
+  ///    vector<int> x{1, 2, 3, 4};     vs.     vector<int> x{ 1, 2, 3, 4 };
+  ///    vector<T> x{{}, {}, {}, {}};           vector<T> x{ {}, {}, {}, {} };
+  ///    f(MyMap[{composite, key}]);            f(MyMap[{ composite, key }]);
+  ///    new int[3]{1, 2, 3};                   new int[3]{ 1, 2, 3 };
+  /// \endcode
   bool Cpp11BracedListStyle;
 
   /// \brief If ``true``, analyze the formatted file for the most common
   /// alignment of ``&`` and ``*``. ``PointerAlignment`` is then used only as
   /// fallback.
+  /// \code
+  ///    original:                      vs.     true:
+  ///    int *foo = 2;                          int *foo = 2;
+  ///    int &j = i;                            int &j = i;
+  ///    int *k = & j;                          int *k = &j;
+  ///    T* k = &j;                             T *k = &j;
+  /// \endcode
   bool DerivePointerAlignment;
 
   /// \brief Disables formatting completely.

   ///
   /// When ``false``, use the same indentation level as for the switch statement.
   /// Switch statement body is always indented one level more than case labels.
+  /// \code
+  ///    false:                                 true:
+  ///    switch (fool) {                vs.     switch (fool) {
+  ///    case 1:                                  case 1:
+  ///      bar();                                   bar();
+  ///      break;                                   break;
+  ///    default:                                 default:
+  ///      plop();                                  plop();
+  ///    }                                      }
+  /// \endcode
   bool IndentCaseLabels;
 
   /// \brief The number of columns to use for indentation.
   /// \code
   ///    IndentWidth: 3
+  ///
   ///    void f() {
   ///       someFunction();
   ///       if (true, false) {

 
   /// \brief Indent if a function definition or declaration is wrapped after the
   /// type.
+  /// \code
+  ///    true:
+  ///    LoooooooooooooooooooooooooooooooooooooooongReturnType
+  ///        LoooooooooooooooooooooooooooooooongFunctionDeclaration();
+  ///
+  ///    false:
+  ///    LoooooooooooooooooooooooooooooooooooooooongReturnType
+  ///    LoooooooooooooooooooooooooooooooongFunctionDeclaration();
+  /// \endcode
   bool IndentWrappedFunctionNames;
 
   /// \brief Quotation styles for JavaScript strings. Does not affect template

   /// \endcode
   bool JavaScriptWrapImports;
 
-  /// \brief If true, empty lines at the start of blocks are kept.
+  /// \brief If true, the empty line at the start of blocks is kept.
+  /// \code
+  ///    true:                                  false:
+  ///    if (foo) {                     vs.     if (foo) {
+  ///                                             bar();
+  ///      bar();                               }
+  ///    }
+  /// \endcode
   bool KeepEmptyLinesAtTheStartOfBlocks;
 
   /// \brief Supported languages.

   NamespaceIndentationKind NamespaceIndentation;
 
   /// \brief The number of characters to use for indentation of ObjC blocks.
+  /// \code
+  ///    ObjCBlockIndentWidth: 4
+  ///
+  ///    [operation setCompletionBlock:^{
+  ///        [self onOperationDone];
+  ///    }];
+  /// \endcode
   unsigned ObjCBlockIndentWidth;
 
   /// \brief Add a space after ``@property`` in Objective-C, i.e. use