diff options
Diffstat (limited to 'docs/ClangFormatStyleOptions.rst')
| -rw-r--r-- | docs/ClangFormatStyleOptions.rst | 116 |
1 files changed, 111 insertions, 5 deletions
diff --git a/docs/ClangFormatStyleOptions.rst b/docs/ClangFormatStyleOptions.rst index 07febaf3898b..ce6fae19c09b 100644 --- a/docs/ClangFormatStyleOptions.rst +++ b/docs/ClangFormatStyleOptions.rst @@ -33,6 +33,43 @@ The ``.clang-format`` file uses YAML format: # A comment. ... +The configuration file can consist of several sections each having different +``Language:`` parameter denoting the programming language this section of the +configuration is targeted at. See the description of the **Language** option +below for the list of supported languages. The first section may have no +language set, it will set the default style options for all lanugages. +Configuration sections for specific language will override options set in the +default section. + +When :program:`clang-format` formats a file, it auto-detects the language using +the file name. When formatting standard input or a file that doesn't have the +extension corresponding to its language, ``-assume-filename=`` option can be +used to override the file name :program:`clang-format` uses to detect the +language. + +An example of a configuration file for multiple languages: + +.. code-block:: yaml + + --- + # We'll use defaults from the LLVM style, but with 4 columns indentation. + BasedOnStyle: LLVM + IndentWidth: 4 + --- + Language: Cpp + # Force pointers to the type for C++. + DerivePointerAlignment: false + PointerAlignment: Left + --- + Language: JavaScript + # Use 100 columns for JS. + ColumnLimit: 100 + --- + Language: Proto + # Don't format .proto files. + DisableFormat: true + ... + An easy way to get a valid ``.clang-format`` file containing all configuration options of a certain predefined style is: @@ -48,6 +85,24 @@ is applied for all input files. The format of the configuration is: -style='{key1: value1, key2: value2, ...}' +Disabling Formatting on a Piece of Code +======================================= + +Clang-format understands also special comments that switch formatting in a +delimited range. The code between a comment ``// clang-format off`` or +``/* clang-format off */`` up to a comment ``// clang-format on`` or +``/* clang-format on */`` will not be formatted. The comments themselves +will be formatted (aligned) normally. + +.. code-block:: c++ + + int formatted_code; + // clang-format off + void unformatted_code ; + // clang-format on + void formatted_code_again; + + Configuring Style in Code ========================= @@ -95,10 +150,24 @@ the configuration (without a prefix: ``Auto``). **AccessModifierOffset** (``int``) The extra indent or outdent of access modifiers, e.g. ``public:``. +**AlignAfterOpenBracket** (``bool``) + 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 + **AlignEscapedNewlinesLeft** (``bool``) If ``true``, aligns escaped newlines as far left as possible. Otherwise puts them into the right-most column. +**AlignOperands** (``bool``) + If ``true``, horizontally align operands of binary and ternary + expressions. + **AlignTrailingComments** (``bool``) If ``true``, aligns trailing comments. @@ -111,6 +180,9 @@ the configuration (without a prefix: ``Auto``). E.g., this allows ``if (a) { return; }`` to be put on a single line. +**AllowShortCaseLabelsOnASingleLine** (``bool``) + 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. @@ -121,6 +193,8 @@ the configuration (without a prefix: ``Auto``). Never merge functions into a single line. * ``SFS_Inline`` (in configuration: ``Inline``) Only merge functions defined inside a class. + * ``SFS_Empty`` (in configuration: ``Empty``) + Only merge empty functions. * ``SFS_All`` (in configuration: ``All``) Merge all functions fitting on a single line. @@ -133,6 +207,13 @@ the configuration (without a prefix: ``Auto``). If ``true``, ``while (true) continue;`` can be put on a single line. +**AlwaysBreakAfterDefinitionReturnType** (``bool``) + If ``true``, always break after function definition return types. + + More truthfully called 'break before the identifier following the type + in a function definition'. PenaltyReturnTypeOnItsOwnLine becomes + irrelevant. + **AlwaysBreakBeforeMultilineStrings** (``bool``) If ``true``, always break before multiline string literals. @@ -140,12 +221,26 @@ the configuration (without a prefix: ``Auto``). 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 + same line or will have one line each. + **BinPackParameters** (``bool``) - If ``false``, a function call's or function definition's parameters - will either all be on the same line or will have one line each. + 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. + +**BreakBeforeBinaryOperators** (``BinaryOperatorStyle``) + The way to wrap binary operators. + + Possible values: + + * ``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. -**BreakBeforeBinaryOperators** (``bool``) - If ``true``, binary operators will be placed after line breaks. **BreakBeforeBraces** (``BraceBreakingStyle``) The brace breaking style to use. @@ -158,7 +253,7 @@ the configuration (without a prefix: ``Auto``). Like ``Attach``, but break before braces on function, namespace and class definitions. * ``BS_Stroustrup`` (in configuration: ``Stroustrup``) - Like ``Attach``, but break before function definitions. + Like ``Attach``, but break before function definitions, and 'else'. * ``BS_Allman`` (in configuration: ``Allman``) Always break before braces. * ``BS_GNU`` (in configuration: ``GNU``) @@ -267,6 +362,8 @@ the configuration (without a prefix: ``Auto``). 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``) @@ -290,6 +387,9 @@ the configuration (without a prefix: ``Auto``). 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)``. @@ -330,6 +430,9 @@ the configuration (without a prefix: ``Auto``). Align pointer in the middle. +**SpaceAfterCStyleCast** (``bool``) + If ``true``, a space may be inserted after C style casts. + **SpaceBeforeAssignmentOperators** (``bool``) If ``false``, spaces will be removed before assignment operators. @@ -374,6 +477,9 @@ the configuration (without a prefix: ``Auto``). **SpacesInParentheses** (``bool``) If ``true``, spaces will be inserted after '(' and before ')'. +**SpacesInSquareBrackets** (``bool``) + 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. |