Index: docs/ClangFormatStyleOptions.rst =================================================================== --- docs/ClangFormatStyleOptions.rst +++ docs/ClangFormatStyleOptions.rst @@ -327,7 +327,7 @@ **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 @@ 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,14 +649,47 @@ * ``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``) The brace breaking style to use. @@ -837,6 +896,12 @@ 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,8 +1044,18 @@ **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 + Indent if a function definition or declaration is wrapped afte the type. **JavaScriptQuotes** (``JavaScriptQuoteStyle``) @@ -1037,6 +1112,33 @@ **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. @@ -1043,6 +1145,17 @@ **MaxEmptyLinesToKeep** (``unsigned``) The maximum number of consecutive empty lines to keep. + .. code-block:: c++ + + MaxEmptyLinesToKeep: 1 vs. MaxEmptyLinesToKeep: 1 + 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,14 +1164,41 @@ * ``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``) The number of characters to use for indentation of ObjC blocks. @@ -1120,6 +1260,18 @@ **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,10 +1314,26 @@ * ``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 @@ -1172,11 +1340,37 @@ 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: + void f( ) { + int x[] = {foo( ), bar( )}; + if (true) { + f( ); + } + } + + false: + void f() { + int x[] = {foo(), bar()}; + if (true) { + f(); + } + } + **SpacesBeforeTrailingComments** (``unsigned``) The number of spaces before trailing line comments (``//`` - comments). @@ -1185,6 +1379,15 @@ 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. @@ -1376,4 +1579,3 @@ r(); } } - Index: include/clang/Format/Format.h =================================================================== --- include/clang/Format/Format.h +++ include/clang/Format/Format.h @@ -204,7 +204,7 @@ 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 @@ }; /// \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 @@ /// \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 @@ /// \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 @@ 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 @@ -878,6 +946,32 @@ 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. @@ -884,15 +978,49 @@ std::string MacroBlockEnd; /// \brief The maximum number of consecutive empty lines to keep. + /// \code + /// MaxEmptyLinesToKeep: 1 vs. MaxEmptyLinesToKeep: 1 + /// 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 +1080,17 @@ 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 +1126,35 @@ /// \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 +1162,23 @@ SpaceBeforeParensOptions SpaceBeforeParens; /// \brief If ``true``, spaces may be inserted into ``()``. + /// \code + /// true: + /// void f( ) { + /// int x[] = {foo( ), bar( )}; + /// if (true) { + /// f( ); + /// } + /// } + /// + /// false: + /// void f() { + /// int x[] = {foo(), bar()}; + /// if (true) { + /// f(); + /// } + /// } + /// \endcode bool SpaceInEmptyParentheses; /// \brief The number of spaces before trailing line comments @@ -1010,6 +1187,14 @@ /// 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 ``>``