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 ↗

(On Diff #91001)

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

726 ↗

(On Diff #91001)

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

[sylvestre.ledru]

with the changes, I will land it now

cfe/trunk/docs/ClangFormatStyleOptions.rst

**AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``)
   Possible values:
 
   * ``SFS_None`` (in configuration: ``None``)
     Never merge functions into a single line.
 
   * ``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.
 
 **AllowShortLoopsOnASingleLine** (``bool``)
   If ``true``, ``while (true) continue;`` can be put on a single
   line.
**AlwaysBreakAfterReturnType** (``ReturnTypeBreakingStyle``)
   The function declaration return type breaking style to use.
 
   Possible values:
 
   * ``RTBS_None`` (in configuration: ``None``)
     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.
 
   This flag is mean to make cases where there are multiple multiline strings
   in a file look more consistent. Thus, it will only take effect if wrapping
   the string at that point leads to it being indented

 **PointerAlignment** (``PointerAlignmentStyle``)
   Pointer and reference alignment style.
 
   Possible values:
 
   * ``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.
 
   .. code-block:: c++
 
      true:                                  false:
      template <int> void foo();     vs.     template<int> void foo();

cfe/trunk/include/clang/Format/Format.h

struct FormatStyle {
   bool AllowShortCaseLabelsOnASingleLine;
 
   /// \brief Different styles for merging short functions containing at most one
   /// statement.
   enum ShortFunctionStyle {
     /// \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,
   };
 
   /// \brief Dependent on the value, ``int f() { return 0; }`` can be put on a
   /// single line.
   ShortFunctionStyle AllowShortFunctionsOnASingleLine;
 
   /// \brief If ``true``, ``if (a) return;`` can be put on a single line.
   bool AllowShortIfStatementsOnASingleLine;
 
   /// \brief If ``true``, ``while (true) continue;`` can be put on a single
   /// line.
   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.
     DRTBS_None,
     /// Always break after the return type.
     DRTBS_All,
     /// Always break after the return types of top-level functions.
     DRTBS_TopLevel,
   };
 
   /// \brief Different ways to break after the function definition or
   /// declaration return type.
   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 function definition return type breaking style to use.  This
   /// option is deprecated and is retained for backwards compatibility.
   DefinitionReturnTypeBreakingStyle AlwaysBreakAfterDefinitionReturnType;
 
   /// \brief The function declaration return type breaking style to use.
struct FormatStyle {
 
   /// \brief Penalty for putting the return type of a function onto its own
   /// line.
   unsigned PenaltyReturnTypeOnItsOwnLine;
 
   /// \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
   };
 
   /// \brief Pointer and reference alignment style.
   PointerAlignmentStyle PointerAlignment;
 
   /// \brief If ``true``, clang-format will attempt to re-flow comments.
   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.
   /// \code
   ///    true:                                  false:
   ///    template <int> void foo();     vs.     template<int> void foo();
   /// \endcode
   bool SpaceAfterTemplateKeyword;