diff options
Diffstat (limited to 'docs/ClangFormatStyleOptions.rst')
-rw-r--r-- | docs/ClangFormatStyleOptions.rst | 170 |
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 ======== |