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:: java
+
+     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
+
+     int i =         //  VeryVeryVeryVeryVeryLongComment
+       longFunction( // Again a long comment
+         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.
+  alignment of ``&`` and ``*``.
+  Pointer and reference alignment styles are going to be updated according
+  to the preferences found in the file.
+  ``PointerAlignment`` is then used only as fallback.
 
 **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:: objc
+
+     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

     SFS_Empty,
     /// \brief Only merge functions defined inside a class. Implies "empty".
     /// \code
-    ///   class {
+    ///   class Foo {
     ///     void f() { foo(); }
     ///   };
     /// \endcode

     SFS_Inline,
     /// \brief Merge all functions fitting on a single line.
     /// \code
-    ///   class {
+    ///   class Foo {
     ///     void f() { foo(); }
     ///   };
     ///   void f() { bar(); }

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

   /// \brief A regular expression that describes comments with special meaning,
   /// which should not be split into lines or otherwise changed.
   /// \code
-  ///    CommentPragmas: '^ FOOBAR pragma:'
+  ///    // CommentPragmas: '^ FOOBAR pragma:'
   ///    // Will leave the following line unaffected
   ///    #include <vector> // FOOBAR pragma: keep
   /// \endcode

   unsigned ConstructorInitializerIndentWidth;
 
   /// \brief Indent width for line continuations.
+  /// \code
+  ///    ContinuationIndentWidth: 2
+  ///
+  ///    int i =         //  VeryVeryVeryVeryVeryLongComment
+  ///      longFunction( // Again a long comment
+  ///        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.
+  /// alignment of ``&`` and ``*``.
+  /// Pointer and reference alignment styles are going to be updated according
+  /// to the preferences found in the file.
+  /// ``PointerAlignment`` is then used only as fallback.
   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{.objc}
+  ///    ObjCBlockIndentWidth: 4
+  ///
+  ///    [operation setCompletionBlock:^{
+  ///        [self onOperationDone];
+  ///    }];
+  /// \endcode
   unsigned ObjCBlockIndentWidth;
 
   /// \brief Add a space after ``@property`` in Objective-C, i.e. use