diff options
Diffstat (limited to 'docs/ClangFormatStyleOptions.rst')
| -rw-r--r-- | docs/ClangFormatStyleOptions.rst | 183 |
1 files changed, 176 insertions, 7 deletions
diff --git a/docs/ClangFormatStyleOptions.rst b/docs/ClangFormatStyleOptions.rst index 054d5c32c6..3611bdd7b0 100644 --- a/docs/ClangFormatStyleOptions.rst +++ b/docs/ClangFormatStyleOptions.rst @@ -7,8 +7,8 @@ supported by :doc:`LibFormat` and :doc:`ClangFormat`. When using :program:`clang-format` command line utility or ``clang::format::reformat(...)`` functions from code, one can either use one of -the predefined styles (LLVM, Google, Chromium, Mozilla, WebKit) or create a -custom style by configuring specific style options. +the predefined styles (LLVM, Google, Chromium, Mozilla, WebKit, Microsoft) or +create a custom style by configuring specific style options. Configuring Style with clang-format @@ -68,6 +68,10 @@ An example of a configuration file for multiple languages: Language: Proto # Don't format .proto files. DisableFormat: true + --- + Language: CSharp + # Use 100 columns for C#. + ColumnLimit: 100 ... An easy way to get a valid ``.clang-format`` file containing all configuration @@ -137,13 +141,16 @@ the configuration (without a prefix: ``Auto``). <http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml>`_ * ``Chromium`` A style complying with `Chromium's style guide - <http://www.chromium.org/developers/coding-style>`_ + <https://www.chromium.org/developers/coding-style>`_ * ``Mozilla`` A style complying with `Mozilla's style guide <https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style>`_ * ``WebKit`` A style complying with `WebKit's style guide - <http://www.webkit.org/coding/coding-style.html>`_ + <https://www.webkit.org/coding/coding-style.html>`_ + * ``Microsoft`` + A style complying with `Microsoft's style guide + <https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-code-style-settings-reference?view=vs-2017>`_ .. START_FORMAT_STYLE_OPTIONS @@ -270,6 +277,41 @@ the configuration (without a prefix: ``Auto``). int a; // My comment a vs. int a; // My comment a int b = 2; // comment b int b = 2; // comment about b +**AllowAllArgumentsOnNextLine** (``bool``) + If a function call or braced initializer list doesn't fit on a + line, allow putting all arguments onto the next line, even if + ``BinPackArguments`` is ``false``. + + .. code-block:: c++ + + true: + callFunction( + a, b, c, d); + + false: + callFunction(a, + b, + c, + d); + +**AllowAllConstructorInitializersOnNextLine** (``bool``) + If a constructor definition with a member initializer list doesn't + fit on a single line, allow putting all member initializers onto the next + line, if ```ConstructorInitializerAllOnOneLineOrOnePerLine``` is true. + Note that this parameter has no effect if + ```ConstructorInitializerAllOnOneLineOrOnePerLine``` is false. + + .. code-block:: c++ + + true: + MyClass::MyClass() : + member0(0), member1(2) {} + + false: + MyClass::MyClass() : + member0(0), + member1(2) {} + **AllowAllParametersOfDeclarationOnNextLine** (``bool``) If the function declaration doesn't fit on a line, allow putting all parameters of a function declaration onto @@ -367,9 +409,84 @@ the configuration (without a prefix: ``Auto``). -**AllowShortIfStatementsOnASingleLine** (``bool``) +**AllowShortIfStatementsOnASingleLine** (``ShortIfStyle``) If ``true``, ``if (a) return;`` can be put on a single line. + Possible values: + + * ``SIS_Never`` (in configuration: ``Never``) + Never put short ifs on the same line. + + .. code-block:: c++ + + if (a) + return ; + else { + return; + } + + * ``SIS_WithoutElse`` (in configuration: ``WithoutElse``) + Without else put short ifs on the same line only if + the else is not a compound statement. + + .. code-block:: c++ + + if (a) return; + else + return; + + * ``SIS_Always`` (in configuration: ``Always``) + Always put short ifs on the same line if + the else is not a compound statement or not. + + .. code-block:: c++ + + if (a) return; + else { + return; + } + + + +**AllowShortLambdasOnASingleLine** (``ShortLambdaStyle``) + Dependent on the value, ``auto lambda []() { return 0; }`` can be put on a + single line. + + Possible values: + + * ``SLS_None`` (in configuration: ``None``) + Never merge lambdas into a single line. + + * ``SLS_Empty`` (in configuration: ``Empty``) + Only merge empty lambdas. + + .. code-block:: c++ + + auto lambda = [](int a) {} + auto lambda2 = [](int a) { + return a; + }; + + * ``SLS_Inline`` (in configuration: ``Inline``) + Merge lambda into a single line if argument of a function. + + .. code-block:: c++ + + auto lambda = [](int a) { + return a; + }; + sort(a.begin(), a.end(), ()[] { return x < y; }) + + * ``SLS_All`` (in configuration: ``All``) + Merge all lambdas fitting on a single line. + + .. code-block:: c++ + + auto lambda = [](int a) {} + auto lambda2 = [](int a) { return a; }; + + + **AllowShortLoopsOnASingleLine** (``bool``) If ``true``, ``while (true) continue;`` can be put on a single line. @@ -587,6 +704,23 @@ the configuration (without a prefix: ``Auto``). Nested configuration flags: + * ``bool AfterCaseLabel`` Wrap case labels. + + .. code-block:: c++ + + false: true: + switch (foo) { vs. switch (foo) { + case 1: { case 1: + bar(); { + break; bar(); + } break; + default: { } + plop(); default: + } { + } plop(); + } + } + * ``bool AfterClass`` Wrap class definitions. .. code-block:: c++ @@ -1212,7 +1346,7 @@ the configuration (without a prefix: ``Auto``). true: false: namespace a { vs. namespace a { foo(); foo(); - } // namespace a; } + } // namespace a } **ForEachMacros** (``std::vector<std::string>``) A vector of macros that should be interpreted as foreach loops @@ -1278,7 +1412,7 @@ the configuration (without a prefix: ``Auto``). used for ordering ``#includes``. `POSIX extended - <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html>`_ + <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html>`_ regular expressions are supported. These regular expressions are matched against the filename of an include @@ -1365,6 +1499,17 @@ the configuration (without a prefix: ``Auto``). # endif #endif + * ``PPDIS_BeforeHash`` (in configuration: ``BeforeHash``) + Indents directives before the hash. + + .. code-block:: c++ + + #if FOO + #if BAR + #include <foo> + #endif + #endif + **IndentWidth** (``unsigned``) @@ -1496,6 +1641,9 @@ the configuration (without a prefix: ``Auto``). * ``LK_Cpp`` (in configuration: ``Cpp``) Should be used for C, C++. + * ``LK_CSharp`` (in configuration: ``CSharp``) + Should be used for C#. + * ``LK_Java`` (in configuration: ``Java``) Should be used for Java. @@ -1812,6 +1960,14 @@ the configuration (without a prefix: ``Auto``). true: false: (int) i; vs. (int)i; +**SpaceAfterLogicalNot** (``bool``) + If ``true``, a space is inserted after the logical not operator (``!``). + + .. code-block:: c++ + + true: false: + ! someExpression(); vs. !someExpression(); + **SpaceAfterTemplateKeyword** (``bool``) If ``true``, a space will be inserted after the 'template' keyword. @@ -1886,6 +2042,19 @@ the configuration (without a prefix: ``Auto``). } } + * ``SBPO_NonEmptyParentheses`` (in configuration: ``NonEmptyParentheses``) + Put a space before opening parentheses only if the parentheses are not + empty i.e. '()' + + .. code-block:: c++ + + void() { + if (true) { + f(); + g (x, y, z); + } + } + * ``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 |