From 35b392d06970b0402edc324fdb30f51ce3b61ec9 Mon Sep 17 00:00:00 2001 From: Sylvestre Ledru Date: Mon, 20 Mar 2017 12:56:40 +0000 Subject: [PATCH] Add more examples to clang-format configuration Reviewers: djasper Reviewed By: djasper Subscribers: klimek, cfe-commits Differential Revision: https://reviews.llvm.org/D30990 llvm-svn: 298245 --- clang/docs/ClangFormatStyleOptions.rst | 230 ++++++++++++++++++++++++- clang/include/clang/Format/Format.h | 208 +++++++++++++++++++++- 2 files changed, 434 insertions(+), 4 deletions(-) diff --git a/clang/docs/ClangFormatStyleOptions.rst b/clang/docs/ClangFormatStyleOptions.rst index 7b13a7d009c6..d3576f97c894 100644 --- a/clang/docs/ClangFormatStyleOptions.rst +++ b/clang/docs/ClangFormatStyleOptions.rst @@ -327,7 +327,7 @@ the configuration (without a prefix: ``Auto``). **AlwaysBreakAfterDefinitionReturnType** (``DefinitionReturnTypeBreakingStyle``) The function definition return type breaking style to use. This - option is deprecated and is retained for backwards compatibility. + option is **deprecated** and is retained for backwards compatibility. Possible values: @@ -455,10 +455,36 @@ the configuration (without a prefix: ``Auto``). If ``false``, a function call's arguments will either be all on the same line or will have one line each. + .. code-block:: c++ + + true: + void f() { + f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa, + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa); + } + + false: + void f() { + f(aaaaaaaaaaaaaaaaaaaa, + aaaaaaaaaaaaaaaaaaaa, + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa); + } + **BinPackParameters** (``bool``) 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. + .. code-block:: c++ + + true: + void f(int aaaaaaaaaaaaaaaaaaaa, int aaaaaaaaaaaaaaaaaaaa, + int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {} + + false: + void f(int aaaaaaaaaaaaaaaaaaaa, + int aaaaaaaaaaaaaaaaaaaa, + int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {} + **BraceWrapping** (``BraceWrappingFlags``) Control of individual brace wrapping cases. @@ -623,12 +649,45 @@ the configuration (without a prefix: ``Auto``). * ``BOS_None`` (in configuration: ``None``) Break after operators. + .. code-block:: c++ + + LooooooooooongType loooooooooooooooooooooongVariable = + someLooooooooooooooooongFunction(); + + bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa == + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa && + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa > + ccccccccccccccccccccccccccccccccccccccccc; + * ``BOS_NonAssignment`` (in configuration: ``NonAssignment``) Break before operators that aren't assignments. + .. code-block:: c++ + + LooooooooooongType loooooooooooooooooooooongVariable = + someLooooooooooooooooongFunction(); + + bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + > ccccccccccccccccccccccccccccccccccccccccc; + * ``BOS_All`` (in configuration: ``All``) Break before operators. + .. code-block:: c++ + + LooooooooooongType loooooooooooooooooooooongVariable + = someLooooooooooooooooongFunction(); + + bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + > ccccccccccccccccccccccccccccccccccccccccc; + **BreakBeforeBraces** (``BraceBreakingStyle``) @@ -837,6 +896,12 @@ the configuration (without a prefix: ``Auto``). A regular expression that describes comments with special meaning, which should not be split into lines or otherwise changed. + .. code-block:: c++ + + CommentPragmas: '^ FOOBAR pragma:' + // Will leave the following line unaffected + #include // FOOBAR pragma: keep + **ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``) If the constructor initializers don't fit on a line, put each initializer on its own line. @@ -979,6 +1044,16 @@ the configuration (without a prefix: ``Auto``). **IndentWidth** (``unsigned``) The number of columns to use for indentation. + .. code-block:: c++ + + IndentWidth: 3 + void f() { + someFunction(); + if (true, false) { + f(); + } + } + **IndentWrappedFunctionNames** (``bool``) Indent if a function definition or declaration is wrapped after the type. @@ -991,17 +1066,44 @@ the configuration (without a prefix: ``Auto``). * ``JSQS_Leave`` (in configuration: ``Leave``) Leave string quotes as they are. + .. code-block:: js + + string1 = "foo"; + string2 = 'bar'; + * ``JSQS_Single`` (in configuration: ``Single``) Always use single quotes. + .. code-block:: js + + string1 = 'foo'; + string2 = 'bar'; + * ``JSQS_Double`` (in configuration: ``Double``) Always use double quotes. + .. code-block:: js + + string1 = "foo"; + string2 = "bar"; + **JavaScriptWrapImports** (``bool``) Whether to wrap JavaScript import/export statements. + .. code-block:: js + + true: + import { + VeryLongImportsAreAnnoying, + VeryLongImportsAreAnnoying, + VeryLongImportsAreAnnoying, + } from 'some/module.js' + + false: + import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js" + **KeepEmptyLinesAtTheStartOfBlocks** (``bool``) If true, empty lines at the start of blocks are kept. @@ -1037,12 +1139,49 @@ the configuration (without a prefix: ``Auto``). **MacroBlockBegin** (``std::string``) A regular expression matching macros that start a block. + .. code-block:: c++ + + # With: + MacroBlockBegin: "^NS_MAP_BEGIN|\ + NS_TABLE_HEAD$" + MacroBlockEnd: "^\ + NS_MAP_END|\ + NS_TABLE_.*_END$" + + NS_MAP_BEGIN + foo(); + NS_MAP_END + + NS_TABLE_HEAD + bar(); + NS_TABLE_FOO_END + + # Without: + NS_MAP_BEGIN + foo(); + NS_MAP_END + + NS_TABLE_HEAD + bar(); + NS_TABLE_FOO_END + **MacroBlockEnd** (``std::string``) A regular expression matching macros that end a block. **MaxEmptyLinesToKeep** (``unsigned``) The maximum number of consecutive empty lines to keep. + .. code-block:: c++ + + MaxEmptyLinesToKeep: 1 vs. MaxEmptyLinesToKeep: 0 + int f() { int f() { + int = 1; int i = 1; + i = foo(); + i = foo(); return i; + } + return i; + } + **NamespaceIndentation** (``NamespaceIndentationKind``) The indentation used for namespaces. @@ -1051,12 +1190,39 @@ the configuration (without a prefix: ``Auto``). * ``NI_None`` (in configuration: ``None``) Don't indent in namespaces. + .. code-block:: c++ + + namespace out { + int i; + namespace in { + int i; + } + } + * ``NI_Inner`` (in configuration: ``Inner``) Indent only in inner namespaces (nested in other namespaces). + .. code-block:: c++ + + namespace out { + int i; + namespace in { + int i; + } + } + * ``NI_All`` (in configuration: ``All``) Indent in all namespaces. + .. code-block:: c++ + + namespace out { + int i; + namespace in { + int i; + } + } + **ObjCBlockIndentWidth** (``unsigned``) @@ -1120,6 +1286,18 @@ the configuration (without a prefix: ``Auto``). **ReflowComments** (``bool``) If ``true``, clang-format will attempt to re-flow comments. + .. code-block:: c++ + + false: + // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information + /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */ + + true: + // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of + // information + /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of + * information */ + **SortIncludes** (``bool``) If ``true``, clang-format will sort ``#includes``. @@ -1162,21 +1340,55 @@ the configuration (without a prefix: ``Auto``). * ``SBPO_Never`` (in configuration: ``Never``) Never put a space before opening parentheses. + .. code-block:: c++ + + void f() { + if(true) { + f(); + } + } + * ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``) Put a space before opening parentheses only after control statement keywords (``for/if/while...``). + .. code-block:: c++ + + void f() { + if (true) { + f(); + } + } + * ``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 when determined by other style rules (after unary operators, opening parentheses, etc.) + .. code-block:: c++ + + void f () { + if (true) { + f (); + } + } + **SpaceInEmptyParentheses** (``bool``) If ``true``, spaces may be inserted into ``()``. + .. code-block:: c++ + + true: false: + void f( ) { vs. void f() { + int x[] = {foo( ), bar( )}; int x[] = {foo(), bar()}; + if (true) { if (true) { + f( ); f(); + } } + } } + **SpacesBeforeTrailingComments** (``unsigned``) The number of spaces before trailing line comments (``//`` - comments). @@ -1185,6 +1397,15 @@ the configuration (without a prefix: ``Auto``). those commonly have different usage patterns and a number of special cases. + .. code-block:: c++ + + SpacesBeforeTrailingComments: 3 + void f() { + if (true) { // foo1 + f(); // bar + } // foo + } + **SpacesInAngles** (``bool``) If ``true``, spaces will be inserted after ``<`` and before ``>`` in template argument lists. @@ -1207,6 +1428,12 @@ the configuration (without a prefix: ``Auto``). If ``true``, spaces are inserted inside container literals (e.g. ObjC and Javascript array and dict literals). + .. code-block:: js + + true: false: + var arr = [ 1, 2, 3 ]; vs. var arr = [1, 2, 3]; + f({a : 1, b : 2, c : 3}); f({a: 1, b: 2, c: 3}); + **SpacesInParentheses** (``bool``) If ``true``, spaces will be inserted after ``(`` and before ``)``. @@ -1376,4 +1603,3 @@ The result is: r(); } } - diff --git a/clang/include/clang/Format/Format.h b/clang/include/clang/Format/Format.h index b856bfd31a21..27c913f07cfa 100644 --- a/clang/include/clang/Format/Format.h +++ b/clang/include/clang/Format/Format.h @@ -204,7 +204,7 @@ struct FormatStyle { bool AllowShortLoopsOnASingleLine; /// \brief Different ways to break after the function definition return type. - /// This option is deprecated and is retained for backwards compatibility. + /// This option is **deprecated** and is retained for backwards compatibility. enum DefinitionReturnTypeBreakingStyle { /// Break after return type automatically. /// ``PenaltyReturnTypeOnItsOwnLine`` is taken into account. @@ -287,7 +287,7 @@ struct FormatStyle { }; /// \brief The function definition return type breaking style to use. This - /// option is deprecated and is retained for backwards compatibility. + /// option is **deprecated** and is retained for backwards compatibility. DefinitionReturnTypeBreakingStyle AlwaysBreakAfterDefinitionReturnType; /// \brief The function declaration return type breaking style to use. @@ -318,19 +318,73 @@ struct FormatStyle { /// \brief If ``false``, a function call's arguments will either be all on the /// same line or will have one line each. + /// \code + /// true: + /// void f() { + /// f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa, + /// aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa); + /// } + /// + /// false: + /// void f() { + /// f(aaaaaaaaaaaaaaaaaaaa, + /// aaaaaaaaaaaaaaaaaaaa, + /// aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa); + /// } + /// \endcode bool BinPackArguments; /// \brief 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. + /// \code + /// true: + /// void f(int aaaaaaaaaaaaaaaaaaaa, int aaaaaaaaaaaaaaaaaaaa, + /// int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {} + /// + /// false: + /// void f(int aaaaaaaaaaaaaaaaaaaa, + /// int aaaaaaaaaaaaaaaaaaaa, + /// int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {} + /// \endcode bool BinPackParameters; /// \brief The style of breaking before or after binary operators. enum BinaryOperatorStyle { /// Break after operators. + /// \code + /// LooooooooooongType loooooooooooooooooooooongVariable = + /// someLooooooooooooooooongFunction(); + /// + /// bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + + /// aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa == + /// aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa && + /// aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa > + /// ccccccccccccccccccccccccccccccccccccccccc; + /// \endcode BOS_None, /// Break before operators that aren't assignments. + /// \code + /// LooooooooooongType loooooooooooooooooooooongVariable = + /// someLooooooooooooooooongFunction(); + /// + /// bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + /// + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + /// == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + /// && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + /// > ccccccccccccccccccccccccccccccccccccccccc; + /// \endcode BOS_NonAssignment, /// Break before operators. + /// \code + /// LooooooooooongType loooooooooooooooooooooongVariable + /// = someLooooooooooooooooongFunction(); + /// + /// bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + /// + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + /// == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + /// && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + /// > ccccccccccccccccccccccccccccccccccccccccc; + /// \endcode BOS_All, }; @@ -665,6 +719,11 @@ struct FormatStyle { /// \brief A regular expression that describes comments with special meaning, /// which should not be split into lines or otherwise changed. + /// \code + /// CommentPragmas: '^ FOOBAR pragma:' + /// // Will leave the following line unaffected + /// #include // FOOBAR pragma: keep + /// \endcode std::string CommentPragmas; /// \brief If ``true``, in the class inheritance expression clang-format will @@ -824,6 +883,15 @@ struct FormatStyle { bool IndentCaseLabels; /// \brief The number of columns to use for indentation. + /// \code + /// IndentWidth: 3 + /// void f() { + /// someFunction(); + /// if (true, false) { + /// f(); + /// } + /// } + /// \endcode unsigned IndentWidth; /// \brief Indent if a function definition or declaration is wrapped after the @@ -834,10 +902,22 @@ struct FormatStyle { /// strings. enum JavaScriptQuoteStyle { /// Leave string quotes as they are. + /// \code{.js} + /// string1 = "foo"; + /// string2 = 'bar'; + /// \endcode JSQS_Leave, /// Always use single quotes. + /// \code{.js} + /// string1 = 'foo'; + /// string2 = 'bar'; + /// \endcode JSQS_Single, /// Always use double quotes. + /// \code{.js} + /// string1 = "foo"; + /// string2 = "bar"; + /// \endcode JSQS_Double }; @@ -845,6 +925,17 @@ struct FormatStyle { JavaScriptQuoteStyle JavaScriptQuotes; /// \brief Whether to wrap JavaScript import/export statements. + /// \code{.js} + /// true: + /// import { + /// VeryLongImportsAreAnnoying, + /// VeryLongImportsAreAnnoying, + /// VeryLongImportsAreAnnoying, + /// } from 'some/module.js' + /// + /// false: + /// import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js" + /// \endcode bool JavaScriptWrapImports; /// \brief If true, empty lines at the start of blocks are kept. @@ -878,21 +969,80 @@ struct FormatStyle { LanguageKind Language; /// \brief A regular expression matching macros that start a block. + /// \code + /// # With: + /// MacroBlockBegin: "^NS_MAP_BEGIN|\ + /// NS_TABLE_HEAD$" + /// MacroBlockEnd: "^\ + /// NS_MAP_END|\ + /// NS_TABLE_.*_END$" + /// + /// NS_MAP_BEGIN + /// foo(); + /// NS_MAP_END + /// + /// NS_TABLE_HEAD + /// bar(); + /// NS_TABLE_FOO_END + /// + /// # Without: + /// NS_MAP_BEGIN + /// foo(); + /// NS_MAP_END + /// + /// NS_TABLE_HEAD + /// bar(); + /// NS_TABLE_FOO_END + /// \endcode std::string MacroBlockBegin; /// \brief A regular expression matching macros that end a block. std::string MacroBlockEnd; /// \brief The maximum number of consecutive empty lines to keep. + /// \code + /// MaxEmptyLinesToKeep: 1 vs. MaxEmptyLinesToKeep: 0 + /// int f() { int f() { + /// int = 1; int i = 1; + /// i = foo(); + /// i = foo(); return i; + /// } + /// return i; + /// } + /// \endcode unsigned MaxEmptyLinesToKeep; /// \brief Different ways to indent namespace contents. enum NamespaceIndentationKind { /// Don't indent in namespaces. + /// \code + /// namespace out { + /// int i; + /// namespace in { + /// int i; + /// } + /// } + /// \endcode NI_None, /// Indent only in inner namespaces (nested in other namespaces). + /// \code + /// namespace out { + /// int i; + /// namespace in { + /// int i; + /// } + /// } + /// \endcode NI_Inner, /// Indent in all namespaces. + /// \code + /// namespace out { + /// int i; + /// namespace in { + /// int i; + /// } + /// } + /// \endcode NI_All }; @@ -952,6 +1102,17 @@ struct FormatStyle { PointerAlignmentStyle PointerAlignment; /// \brief If ``true``, clang-format will attempt to re-flow comments. + /// \code + /// false: + /// // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information + /// /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */ + /// + /// true: + /// // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of + /// // information + /// /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of + /// * information */ + /// \endcode bool ReflowComments; /// \brief If ``true``, clang-format will sort ``#includes``. @@ -987,14 +1148,35 @@ struct FormatStyle { /// \brief Different ways to put a space before opening parentheses. enum SpaceBeforeParensOptions { /// Never put a space before opening parentheses. + /// \code + /// void f() { + /// if(true) { + /// f(); + /// } + /// } + /// \endcode SBPO_Never, /// Put a space before opening parentheses only after control statement /// keywords (``for/if/while...``). + /// \code + /// void f() { + /// if (true) { + /// f(); + /// } + /// } + /// \endcode SBPO_ControlStatements, /// Always put a space before opening parentheses, except when it's /// prohibited by the syntax rules (in function-like macro definitions) or /// when determined by other style rules (after unary operators, opening /// parentheses, etc.) + /// \code + /// void f () { + /// if (true) { + /// f (); + /// } + /// } + /// \endcode SBPO_Always }; @@ -1002,6 +1184,15 @@ struct FormatStyle { SpaceBeforeParensOptions SpaceBeforeParens; /// \brief If ``true``, spaces may be inserted into ``()``. + /// \code + /// true: false: + /// void f( ) { vs. void f() { + /// int x[] = {foo( ), bar( )}; int x[] = {foo(), bar()}; + /// if (true) { if (true) { + /// f( ); f(); + /// } } + /// } } + /// \endcode bool SpaceInEmptyParentheses; /// \brief The number of spaces before trailing line comments @@ -1010,6 +1201,14 @@ struct FormatStyle { /// This does not affect trailing block comments (``/*`` - comments) as /// those commonly have different usage patterns and a number of special /// cases. + /// \code + /// SpacesBeforeTrailingComments: 3 + /// void f() { + /// if (true) { // foo1 + /// f(); // bar + /// } // foo + /// } + /// \endcode unsigned SpacesBeforeTrailingComments; /// \brief If ``true``, spaces will be inserted after ``<`` and before ``>`` @@ -1023,6 +1222,11 @@ struct FormatStyle { /// \brief If ``true``, spaces are inserted inside container literals (e.g. /// ObjC and Javascript array and dict literals). + /// \code{.js} + /// true: false: + /// var arr = [ 1, 2, 3 ]; vs. var arr = [1, 2, 3]; + /// f({a : 1, b : 2, c : 3}); f({a: 1, b: 2, c: 3}); + /// \endcode bool SpacesInContainerLiterals; /// \brief If ``true``, spaces may be inserted into C style casts.