Add more examples to clang-format configuration

[djasper]

Please upload patches with full context or use arc (https://secure.phabricator.com/book/phabricator/article/arcanist/).

Generally looks good, just minor comments.

include/clang/Format/Format.h

201

Don't add examples here as this is deprecated. Maybe make it more obvious that this is deprecated instead.

726

While you are here: s/may be/is/

[sylvestre.ledru]

with the changes, I will land it now

docs/ClangFormatStyleOptions.rst

   * ``SFS_Empty`` (in configuration: ``Empty``)
     Only merge empty functions.
 
+    .. code-block:: c++
+
+      void f() { bar(); }
+      void f2() {
+        bar2();
+      }
+
   * ``SFS_Inline`` (in configuration: ``Inline``)
     Only merge functions defined inside a class. Implies "empty".
 
+    .. code-block:: c++
+
+      class {
+        void f() { foo(); }
+      };
+
   * ``SFS_All`` (in configuration: ``All``)
     Merge all functions fitting on a single line.
 
+    .. code-block:: c++
 
+      class {
+        void f() { foo(); }
+      };
+      void f() { bar(); }
 
+
+
 **AllowShortIfStatementsOnASingleLine** (``bool``)
   If ``true``, ``if (a) return;`` can be put on a single line.
 

     Break after return type automatically.
     ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
 
+    .. code-block:: c++
+
+      class A {
+        int f() { return 0; };
+      };
+      int f();
+      int f() { return 1; }
+
   * ``RTBS_All`` (in configuration: ``All``)
     Always break after the return type.
 
+    .. code-block:: c++
+
+      class A {
+        int
+        f() {
+          return 0;
+        };
+      };
+      int
+      f();
+      int
+      f() {
+        return 1;
+      }
+
   * ``RTBS_TopLevel`` (in configuration: ``TopLevel``)
     Always break after the return types of top-level functions.
 
+    .. code-block:: c++
+
+      class A {
+        int f() { return 0; };
+      };
+      int
+      f();
+      int
+      f() {
+        return 1;
+      }
+
   * ``RTBS_AllDefinitions`` (in configuration: ``AllDefinitions``)
     Always break after the return type of function definitions.
 
+    .. code-block:: c++
+
+      class A {
+        int
+        f() {
+          return 0;
+        };
+      };
+      int f();
+      int
+      f() {
+        return 1;
+      }
+
   * ``RTBS_TopLevelDefinitions`` (in configuration: ``TopLevelDefinitions``)
     Always break after the return type of top-level definitions.
 
+    .. code-block:: c++
 
+      class A {
+        int f() { return 0; };
+      };
+      int f();
+      int
+      f() {
+        return 1;
+      }
 
+
+
 **AlwaysBreakBeforeMultilineStrings** (``bool``)
   If ``true``, always break before multiline string literals.
 

   * ``PAS_Left`` (in configuration: ``Left``)
     Align pointer to the left.
 
+    .. code-block:: c++
+
+      int\* a;
+
   * ``PAS_Right`` (in configuration: ``Right``)
     Align pointer to the right.
 
+    .. code-block:: c++
+
+      int \*a;
+
   * ``PAS_Middle`` (in configuration: ``Middle``)
     Align pointer in the middle.
 
+    .. code-block:: c++
 
+      int \* a;
 
+
+
 **ReflowComments** (``bool``)
   If ``true``, clang-format will attempt to re-flow comments.
 

 **SortIncludes** (``bool``)
   If ``true``, clang-format will sort ``#includes``.
 
+  .. code-block:: c++
+
+     false:                                 true:
+     #include "b.h"                 vs.     #include "a.h"
+     #include "a.h"                         #include "b.h"
+
 **SpaceAfterCStyleCast** (``bool``)
-  If ``true``, a space may be inserted after C style casts.
+  If ``true``, a space is inserted after C style casts.
 
+  .. code-block:: c++
+
+     true:                                  false:
+     (int)i;                        vs.     (int) i;
+
 **SpaceAfterTemplateKeyword** (``bool``)
   If ``true``, a space will be inserted after the 'template' keyword.
 

include/clang/Format/Format.h

     /// \brief Never merge functions into a single line.
     SFS_None,
     /// \brief Only merge empty functions.
+    /// \code
+    ///   void f() { bar(); }
+    ///   void f2() {
+    ///     bar2();
+    ///   }
+    /// \endcode
     SFS_Empty,
     /// \brief Only merge functions defined inside a class. Implies "empty".
+    /// \code
+    ///   class {
+    ///     void f() { foo(); }
+    ///   };
+    /// \endcode
     SFS_Inline,
     /// \brief Merge all functions fitting on a single line.
+    /// \code
+    ///   class {
+    ///     void f() { foo(); }
+    ///   };
+    ///   void f() { bar(); }
+    /// \endcode
     SFS_All,
   };
 

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

   enum ReturnTypeBreakingStyle {
     /// Break after return type automatically.
     /// ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
+    /// \code
+    ///   class A {
+    ///     int f() { return 0; };
+    ///   };
+    ///   int f();
+    ///   int f() { return 1; }
+    /// \endcode
     RTBS_None,
     /// Always break after the return type.
+    /// \code
+    ///   class A {
+    ///     int
+    ///     f() {
+    ///       return 0;
+    ///     };
+    ///   };
+    ///   int
+    ///   f();
+    ///   int
+    ///   f() {
+    ///     return 1;
+    ///   }
+    /// \endcode
     RTBS_All,
     /// Always break after the return types of top-level functions.
+    /// \code
+    ///   class A {
+    ///     int f() { return 0; };
+    ///   };
+    ///   int
+    ///   f();
+    ///   int
+    ///   f() {
+    ///     return 1;
+    ///   }
+    /// \endcode
     RTBS_TopLevel,
     /// Always break after the return type of function definitions.
+    /// \code
+    ///   class A {
+    ///     int
+    ///     f() {
+    ///       return 0;
+    ///     };
+    ///   };
+    ///   int f();
+    ///   int
+    ///   f() {
+    ///     return 1;
+    ///   }
+    /// \endcode
     RTBS_AllDefinitions,
     /// Always break after the return type of top-level definitions.
+    /// \code
+    ///   class A {
+    ///     int f() { return 0; };
+    ///   };
+    ///   int f();
+    ///   int
+    ///   f() {
+    ///     return 1;
+    ///   }
+    /// \endcode
     RTBS_TopLevelDefinitions,
   };
 

   /// \brief The ``&`` and ``*`` alignment style.
   enum PointerAlignmentStyle {
     /// Align pointer to the left.
+    /// \code
+    ///   int* a;
+    /// \endcode
     PAS_Left,
     /// Align pointer to the right.
+    /// \code
+    ///   int *a;
+    /// \endcode
     PAS_Right,
     /// Align pointer in the middle.
+    /// \code
+    ///   int * a;
+    /// \endcode
     PAS_Middle
   };
 

   bool ReflowComments;
 
   /// \brief If ``true``, clang-format will sort ``#includes``.
+  /// \code
+  ///    false:                                 true:
+  ///    #include "b.h"                 vs.     #include "a.h"
+  ///    #include "a.h"                         #include "b.h"
+  /// \endcode
   bool SortIncludes;
 
-  /// \brief If ``true``, a space may be inserted after C style casts.
+  /// \brief If ``true``, a space is inserted after C style casts.
+  /// \code
+  ///    true:                                  false:
+  ///    (int)i;                        vs.     (int) i;
+  /// \endcode
   bool SpaceAfterCStyleCast;
 
   /// \brief If \c true, a space will be inserted after the 'template' keyword.