Clean up clang-format options documentation. NFC

Use uniform style for inline code blocks, specify language for YAML code blocks,
various formatting fixes etc.

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@261645 91177308-0d34-0410-b5e6-96231b3b80d8

docs/ClangFormatStyleOptions.rst

@@ -148,7 +148,7 @@ the configuration (without a prefix: ``Auto``).
 .. START_FORMAT_STYLE_OPTIONS
 
 **AccessModifierOffset** (``int``)
-  The extra indent or outdent of access modifiers, e.g. ``public:``.
+  The extra indent or outdent of access modifiers, e.g. ``public``:.
 
 **AlignAfterOpenBracket** (``BracketAlignmentStyle``)
   If ``true``, horizontally aligns arguments after an open bracket.
@@ -165,6 +165,7 @@ the configuration (without a prefix: ``Auto``).
 
       someLongFunction(argument1,
                        argument2);
+
   * ``BAS_DontAlign`` (in configuration: ``DontAlign``)
     Don't align, instead use ``ContinuationIndentWidth``, e.g.:
 
@@ -172,6 +173,7 @@ the configuration (without a prefix: ``Auto``).
 
       someLongFunction(argument1,
           argument2);
+
   * ``BAS_AlwaysBreak`` (in configuration: ``AlwaysBreak``)
     Always break after an open bracket, if the parameters don't fit
     on a single line, e.g.:
@@ -182,6 +184,7 @@ the configuration (without a prefix: ``Auto``).
           argument1, argument2);
 
 
+
 **AlignConsecutiveAssignments** (``bool``)
   If ``true``, aligns consecutive assignments.
 
@@ -238,28 +241,31 @@ the configuration (without a prefix: ``Auto``).
   If ``true``, short case labels will be contracted to a single line.
 
 **AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``)
-  Dependent on the value, ``int f() { return 0; }`` can be put
-  on a single line.
+  Dependent on the value, ``int f() { return 0; }`` can be put on a
+  single line.
 
   Possible values:
 
   * ``SFS_None`` (in configuration: ``None``)
     Never merge functions into a single line.
+
   * ``SFS_Empty`` (in configuration: ``Empty``)
     Only merge empty functions.
+
   * ``SFS_Inline`` (in configuration: ``Inline``)
     Only merge functions defined inside a class. Implies "empty".
+
   * ``SFS_All`` (in configuration: ``All``)
     Merge all functions fitting on a single line.
 
 
+
 **AllowShortIfStatementsOnASingleLine** (``bool``)
-  If ``true``, ``if (a) return;`` can be put on a single
-  line.
+  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.
+  If ``true``, ``while (true) continue;`` can be put on a single
+  line.
 
 **AlwaysBreakAfterDefinitionReturnType** (``DefinitionReturnTypeBreakingStyle``)
   The function definition return type breaking style to use.  This
@@ -270,12 +276,15 @@ the configuration (without a prefix: ``Auto``).
   * ``DRTBS_None`` (in configuration: ``None``)
     Break after return type automatically.
     ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
+
   * ``DRTBS_All`` (in configuration: ``All``)
     Always break after the return type.
+
   * ``DRTBS_TopLevel`` (in configuration: ``TopLevel``)
     Always break after the return types of top-level functions.
 
 
+
 **AlwaysBreakAfterReturnType** (``ReturnTypeBreakingStyle``)
   The function declaration return type breaking style to use.
 
@@ -284,16 +293,21 @@ the configuration (without a prefix: ``Auto``).
   * ``RTBS_None`` (in configuration: ``None``)
     Break after return type automatically.
     ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
+
   * ``RTBS_All`` (in configuration: ``All``)
     Always break after the return type.
+
   * ``RTBS_TopLevel`` (in configuration: ``TopLevel``)
     Always break after the return types of top-level functions.
+
   * ``RTBS_AllDefinitions`` (in configuration: ``AllDefinitions``)
     Always break after the return type of function definitions.
+
   * ``RTBS_TopLevelDefinitions`` (in configuration: ``TopLevelDefinitions``)
     Always break after the return type of top-level definitions.
 
 
+
 **AlwaysBreakBeforeMultilineStrings** (``bool``)
   If ``true``, always break before multiline string literals.
 
@@ -303,8 +317,8 @@ the configuration (without a prefix: ``Auto``).
   ``ContinuationIndentWidth`` spaces from the start of the line.
 
 **AlwaysBreakTemplateDeclarations** (``bool``)
-  If ``true``, always break after the ``template<...>`` of a
-  template declaration.
+  If ``true``, always break after the ``template<...>`` of a template
+  declaration.
 
 **BinPackArguments** (``bool``)
   If ``false``, a function call's arguments will either be all on the
@@ -317,17 +331,17 @@ the configuration (without a prefix: ``Auto``).
 **BraceWrapping** (``BraceWrappingFlags``)
   Control of individual brace wrapping cases.
 
-  If ``BreakBeforeBraces`` is set to ``custom``, use this to specify how each
-  individual brace case should be handled. Otherwise, this is ignored.
+  If ``BreakBeforeBraces`` is set to ``BS_Custom``, use this to specify how
+  each individual brace case should be handled. Otherwise, this is ignored.
 
   Nested configuration flags:
 
   * ``bool AfterClass`` Wrap class definitions.
-  * ``bool AfterControlStatement`` Wrap control statements (if/for/while/switch/..).
+  * ``bool AfterControlStatement`` Wrap control statements (``if``/``for``/``while``/``switch``/..).
   * ``bool AfterEnum`` Wrap enum definitions.
   * ``bool AfterFunction`` Wrap function definitions.
   * ``bool AfterNamespace`` Wrap namespace definitions.
-  * ``bool AfterObjCDeclaration`` Wrap ObjC definitions (@autoreleasepool, interfaces, ..).
+  * ``bool AfterObjCDeclaration`` Wrap ObjC definitions (``@autoreleasepool``, interfaces, ..).
   * ``bool AfterStruct`` Wrap struct definitions.
   * ``bool AfterUnion`` Wrap union definitions.
   * ``bool BeforeCatch`` Wrap before ``catch``.
@@ -345,12 +359,15 @@ the configuration (without a prefix: ``Auto``).
 
   * ``BOS_None`` (in configuration: ``None``)
     Break after operators.
+
   * ``BOS_NonAssignment`` (in configuration: ``NonAssignment``)
     Break before operators that aren't assignments.
+
   * ``BOS_All`` (in configuration: ``All``)
     Break before operators.
 
 
+
 **BreakBeforeBraces** (``BraceBreakingStyle``)
   The brace breaking style to use.
 
@@ -358,24 +375,33 @@ the configuration (without a prefix: ``Auto``).
 
   * ``BS_Attach`` (in configuration: ``Attach``)
     Always attach braces to surrounding context.
+
   * ``BS_Linux`` (in configuration: ``Linux``)
     Like ``Attach``, but break before braces on function, namespace and
     class definitions.
+
   * ``BS_Mozilla`` (in configuration: ``Mozilla``)
     Like ``Attach``, but break before braces on enum, function, and record
     definitions.
+
   * ``BS_Stroustrup`` (in configuration: ``Stroustrup``)
-    Like ``Attach``, but break before function definitions, 'catch', and 'else'.
+    Like ``Attach``, but break before function definitions, ``catch``, and
+    ``else``.
+
   * ``BS_Allman`` (in configuration: ``Allman``)
     Always break before braces.
+
   * ``BS_GNU`` (in configuration: ``GNU``)
     Always break before braces and add an extra level of indentation to
     braces of control statements, not to those of class, function
     or other definitions.
+
   * ``BS_WebKit`` (in configuration: ``WebKit``)
     Like ``Attach``, but break before functions.
+
   * ``BS_Custom`` (in configuration: ``Custom``)
-    Configure each individual brace in ``BraceWrapping``.
+    Configure each individual brace in `BraceWrapping`.
+
 
 
 **BreakBeforeTernaryOperators** (``bool``)
@@ -427,7 +453,8 @@ the configuration (without a prefix: ``Auto``).
 
 **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 ``\*``. ``PointerAlignment`` is then used only as
+  fallback.
 
 **DisableFormat** (``bool``)
   Disables formatting completely.
@@ -457,32 +484,32 @@ the configuration (without a prefix: ``Auto``).
 
   In the .clang-format configuration file, this can be configured like:
 
-  .. code-block:: c++
+  .. code-block:: yaml
 
     ForEachMacros: ['RANGES_FOR', 'FOREACH']
 
   For example: BOOST_FOREACH.
 
 **IncludeCategories** (``std::vector<IncludeCategory>``)
-  Regular expressions denoting the different #include categories used
-  for ordering #includes.
+  Regular expressions denoting the different ``#include`` categories
+  used for ordering ``#includes``.
 
   These regular expressions are matched against the filename of an include
   (including the <> or "") in order. The value belonging to the first
-  matching regular expression is assigned and #includes are sorted first
+  matching regular expression is assigned and ``#includes`` are sorted first
   according to increasing category number and then alphabetically within
   each category.
 
   If none of the regular expressions match, INT_MAX is assigned as
   category. The main header for a source file automatically gets category 0.
-  so that it is generally kept at the beginning of the #includes
+  so that it is generally kept at the beginning of the ``#includes``
   (http://llvm.org/docs/CodingStandards.html#include-style). However, you
   can also assign negative priorities if you have certain headers that
   always need to be first.
 
   To configure this in the .clang-format file, use:
 
-  .. code-block:: c++
+  .. code-block:: yaml
 
     IncludeCategories:
       - Regex:           '^"(llvm|llvm-c|clang|clang-c)/'
@@ -515,19 +542,25 @@ the configuration (without a prefix: ``Auto``).
 
   * ``LK_None`` (in configuration: ``None``)
     Do not use.
+
   * ``LK_Cpp`` (in configuration: ``Cpp``)
     Should be used for C, C++, ObjectiveC, ObjectiveC++.
+
   * ``LK_Java`` (in configuration: ``Java``)
     Should be used for Java.
+
   * ``LK_JavaScript`` (in configuration: ``JavaScript``)
     Should be used for JavaScript.
+
   * ``LK_Proto`` (in configuration: ``Proto``)
     Should be used for Protocol Buffers
     (https://developers.google.com/protocol-buffers/).
+
   * ``LK_TableGen`` (in configuration: ``TableGen``)
     Should be used for TableGen code.
 
 
+
 **MacroBlockBegin** (``std::string``)
   A regular expression matching macros that start a block.
 
@@ -544,25 +577,28 @@ the configuration (without a prefix: ``Auto``).
 
   * ``NI_None`` (in configuration: ``None``)
     Don't indent in namespaces.
+
   * ``NI_Inner`` (in configuration: ``Inner``)
     Indent only in inner namespaces (nested in other namespaces).
+
   * ``NI_All`` (in configuration: ``All``)
     Indent in all namespaces.
 
 
+
 **ObjCBlockIndentWidth** (``unsigned``)
   The number of characters to use for indentation of ObjC blocks.
 
 **ObjCSpaceAfterProperty** (``bool``)
   Add a space after ``@property`` in Objective-C, i.e. use
-  ``\@property (readonly)`` instead of ``\@property(readonly)``.
+  ``@property (readonly)`` instead of ``@property(readonly)``.
 
 **ObjCSpaceBeforeProtocolList** (``bool``)
   Add a space in front of an Objective-C protocol list, i.e. use
   ``Foo <Protocol>`` instead of ``Foo<Protocol>``.
 
 **PenaltyBreakBeforeFirstCallParameter** (``unsigned``)
-  The penalty for breaking a function call after "call(".
+  The penalty for breaking a function call after ``call(``.
 
 **PenaltyBreakComment** (``unsigned``)
   The penalty for each line break introduced inside a comment.
@@ -587,17 +623,20 @@ the configuration (without a prefix: ``Auto``).
 
   * ``PAS_Left`` (in configuration: ``Left``)
     Align pointer to the left.
+
   * ``PAS_Right`` (in configuration: ``Right``)
     Align pointer to the right.
+
   * ``PAS_Middle`` (in configuration: ``Middle``)
     Align pointer in the middle.
 
 
+
 **ReflowComments** (``bool``)
-  If true, clang-format will attempt to re-flow comments.
+  If ``true``, clang-format will attempt to re-flow comments.
 
 **SortIncludes** (``bool``)
-  If true, clang-format will sort #includes.
+  If ``true``, clang-format will sort ``#includes``.
 
 **SpaceAfterCStyleCast** (``bool``)
   If ``true``, a space may be inserted after C style casts.
@@ -612,9 +651,11 @@ the configuration (without a prefix: ``Auto``).
 
   * ``SBPO_Never`` (in configuration: ``Never``)
     Never put a space before opening parentheses.
+
   * ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``)
     Put a space before opening parentheses only after control statement
     keywords (``for/if/while...``).
+
   * ``SBPO_Always`` (in configuration: ``Always``)
     Always put a space before opening parentheses, except when it's
     prohibited by the syntax rules (in function-like macro definitions) or
@@ -622,19 +663,21 @@ the configuration (without a prefix: ``Auto``).
     parentheses, etc.)
 
 
+
 **SpaceInEmptyParentheses** (``bool``)
-  If ``true``, spaces may be inserted into '()'.
+  If ``true``, spaces may be inserted into ``()``.
 
 **SpacesBeforeTrailingComments** (``unsigned``)
   The number of spaces before trailing line comments
   (``//`` - comments).
 
-  This does not affect trailing block comments (``/**/`` - comments) as those
-  commonly have different usage patterns and a number of special cases.
+  This does not affect trailing block comments (``/**/`` - comments) as
+  those commonly have different usage patterns and a number of special
+  cases.
 
 **SpacesInAngles** (``bool``)
-  If ``true``, spaces will be inserted after '<' and before '>' in
-  template argument lists
+  If ``true``, spaces will be inserted after ``<`` and before ``>``
+  in template argument lists.
 
 **SpacesInCStyleCastParentheses** (``bool``)
   If ``true``, spaces may be inserted into C style casts.
@@ -644,26 +687,28 @@ the configuration (without a prefix: ``Auto``).
   ObjC and Javascript array and dict literals).
 
 **SpacesInParentheses** (``bool``)
-  If ``true``, spaces will be inserted after '(' and before ')'.
+  If ``true``, spaces will be inserted after ``(`` and before ``)``.
 
 **SpacesInSquareBrackets** (``bool``)
-  If ``true``, spaces will be inserted after '[' and before ']'.
+  If ``true``, spaces will be inserted after ``[`` and before ``]``.
 
 **Standard** (``LanguageStandard``)
-  Format compatible with this standard, e.g. use
-  ``A<A<int> >`` instead of ``A<A<int>>`` for LS_Cpp03.
+  Format compatible with this standard, e.g. use ``A<A<int> >``
+  instead of ``A<A<int>>`` for ``LS_Cpp03``.
 
   Possible values:
 
   * ``LS_Cpp03`` (in configuration: ``Cpp03``)
     Use C++03-compatible syntax.
+
   * ``LS_Cpp11`` (in configuration: ``Cpp11``)
-    Use features of C++11 (e.g. ``A<A<int>>`` instead of
-    ``A<A<int> >``).
+    Use features of C++11 (e.g. ``A<A<int>>`` instead of ``A<A<int> >``).
+
   * ``LS_Auto`` (in configuration: ``Auto``)
     Automatic detection based on the input.
 
 
+
 **TabWidth** (``unsigned``)
   The number of columns used for tab stops.
 
@@ -674,13 +719,16 @@ the configuration (without a prefix: ``Auto``).
 
   * ``UT_Never`` (in configuration: ``Never``)
     Never use tab.
+
   * ``UT_ForIndentation`` (in configuration: ``ForIndentation``)
     Use tabs only for indentation.
+
   * ``UT_Always`` (in configuration: ``Always``)
     Use tabs whenever we need to fill whitespace that spans at least from
     one tab stop to the next one.
 
 
+
 .. END_FORMAT_STYLE_OPTIONS
 
 Adding additional style options