aboutsummaryrefslogtreecommitdiff
path: root/docs/ClangFormatStyleOptions.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/ClangFormatStyleOptions.rst')
-rw-r--r--docs/ClangFormatStyleOptions.rst170
1 files changed, 153 insertions, 17 deletions
diff --git a/docs/ClangFormatStyleOptions.rst b/docs/ClangFormatStyleOptions.rst
index 031daeeaa123..bfabd5985ca0 100644
--- a/docs/ClangFormatStyleOptions.rst
+++ b/docs/ClangFormatStyleOptions.rst
@@ -150,26 +150,61 @@ the configuration (without a prefix: ``Auto``).
**AccessModifierOffset** (``int``)
The extra indent or outdent of access modifiers, e.g. ``public:``.
-**AlignAfterOpenBracket** (``bool``)
+**AlignAfterOpenBracket** (``BracketAlignmentStyle``)
If ``true``, horizontally aligns arguments after an open bracket.
This applies to round brackets (parentheses), angle brackets and square
brackets. This will result in formattings like
- \code
- someLongFunction(argument1,
- argument2);
- \endcode
+
+ Possible values:
+
+ * ``BAS_Align`` (in configuration: ``Align``)
+ Align parameters on the open bracket, e.g.:
+
+ .. code-block:: c++
+
+ someLongFunction(argument1,
+ argument2);
+ * ``BAS_DontAlign`` (in configuration: ``DontAlign``)
+ Don't align, instead use ``ContinuationIndentWidth``, e.g.:
+
+ .. code-block:: c++
+
+ 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.:
+
+ .. code-block:: c++
+
+ someLongFunction(
+ argument1, argument2);
+
**AlignConsecutiveAssignments** (``bool``)
If ``true``, aligns consecutive assignments.
This will align the assignment operators of consecutive lines. This
will result in formattings like
- \code
- int aaaa = 12;
- int b = 23;
- int ccc = 23;
- \endcode
+
+ .. code-block:: c++
+
+ int aaaa = 12;
+ int b = 23;
+ int ccc = 23;
+
+**AlignConsecutiveDeclarations** (``bool``)
+ If ``true``, aligns consecutive declarations.
+
+ This will align the declaration names of consecutive lines. This
+ will result in formattings like
+
+ .. code-block:: c++
+
+ int aaaa = 12;
+ float b = 23;
+ std::string ccc = 23;
**AlignEscapedNewlinesLeft** (``bool``)
If ``true``, aligns escaped newlines as far left as possible.
@@ -219,7 +254,8 @@ the configuration (without a prefix: ``Auto``).
single line.
**AlwaysBreakAfterDefinitionReturnType** (``DefinitionReturnTypeBreakingStyle``)
- The function definition return type breaking style to use.
+ The function definition return type breaking style to use. This
+ option is deprecated and is retained for backwards compatibility.
Possible values:
@@ -229,7 +265,25 @@ the configuration (without a prefix: ``Auto``).
* ``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.
+ Always break after the return types of top-level functions.
+
+
+**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.
+ * ``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``)
@@ -252,6 +306,30 @@ the configuration (without a prefix: ``Auto``).
If ``false``, a function declaration's or function definition's
parameters will either all be on the same line or will have one line each.
+**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.
+
+ Nested configuration flags:
+
+ * ``bool AfterClass`` Wrap class definitions.
+ * ``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 AfterStruct`` Wrap struct definitions.
+ * ``bool AfterUnion`` Wrap union definitions.
+ * ``bool BeforeCatch`` Wrap before ``catch``.
+ * ``bool BeforeElse`` Wrap before ``else``.
+ * ``bool IndentBraces`` Indent the wrapped braces themselves.
+
+
+**BreakAfterJavaFieldAnnotations** (``bool``)
+ Break after each annotation on a field in Java files.
+
**BreakBeforeBinaryOperators** (``BinaryOperatorStyle``)
The way to wrap binary operators.
@@ -279,13 +357,17 @@ the configuration (without a prefix: ``Auto``).
Like ``Attach``, but break before braces on enum, function, and record
definitions.
* ``BS_Stroustrup`` (in configuration: ``Stroustrup``)
- Like ``Attach``, but break before function definitions, 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``.
**BreakBeforeTernaryOperators** (``bool``)
@@ -356,13 +438,47 @@ the configuration (without a prefix: ``Auto``).
instead of as function calls.
These are expected to be macros of the form:
- \code
- FOREACH(<variable-declaration>, ...)
- <loop-body>
- \endcode
+
+ .. code-block:: c++
+
+ FOREACH(<variable-declaration>, ...)
+ <loop-body>
+
+ In the .clang-format configuration file, this can be configured like:
+
+ .. code-block:: c++
+
+ ForEachMacros: ['RANGES_FOR', 'FOREACH']
For example: BOOST_FOREACH.
+**IncludeCategories** (``std::vector<IncludeCategory>``)
+ 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
+ according to increasing category number and then alphabetically within
+ each category.
+
+ If none of the regular expressions match, UINT_MAX is assigned as
+ category. The main header for a source file automatically gets category 0,
+ so that it is kept at the beginning of the #includes
+ (http://llvm.org/docs/CodingStandards.html#include-style).
+
+ To configure this in the .clang-format file, use:
+
+ .. code-block:: c++
+
+ IncludeCategories:
+ - Regex: '^"(llvm|llvm-c|clang|clang-c)/'
+ Priority: 2
+ - Regex: '^(<|"(gtest|isl|json)/)'
+ Priority: 3
+ - Regex: '.\*'
+ Priority: 1
+
**IndentCaseLabels** (``bool``)
Indent case labels one level from the switch statement.
@@ -546,6 +662,26 @@ the configuration (without a prefix: ``Auto``).
.. END_FORMAT_STYLE_OPTIONS
+Adding additional style options
+===============================
+
+Each additional style option adds costs to the clang-format project. Some of
+these costs affect the clang-format developement itself, as we need to make
+sure that any given combination of options work and that new features don't
+break any of the existing options in any way. There are also costs for end users
+as options become less discoverable and people have to think about and make a
+decision on options they don't really care about.
+
+The goal of the clang-format project is more on the side of supporting a
+limited set of styles really well as opposed to supporting every single style
+used by a codebase somewhere in the wild. Of course, we do want to support all
+major projects and thus have established the following bar for adding style
+options. Each new style option must ..
+
+ * be used in a project of significant size (have dozens of contributors)
+ * have a publicly accessible style guide
+ * have a person willing to contribute and maintain patches
+
Examples
========