Index: docs/ClangFormatStyleOptions.rst =================================================================== --- docs/ClangFormatStyleOptions.rst +++ docs/ClangFormatStyleOptions.rst @@ -213,6 +213,13 @@ If ``true``, aligns escaped newlines as far left as possible. Otherwise puts them into the right-most column. + .. code-block:: c++ + + #define A \ + int aaaa; \ + int b; \ + int dddddddddd; + **AlignOperands** (``bool``) If ``true``, horizontally align operands of binary and ternary expressions. @@ -228,6 +235,11 @@ **AlignTrailingComments** (``bool``) If ``true``, aligns trailing comments. + .. code-block:: c++ + + int a; // My comment about a + int b = 2; // comment about b + **AllowAllParametersOfDeclarationOnNextLine** (``bool``) Allow putting all parameters of a function declaration onto the next line even if ``BinPackParameters`` is ``false``. @@ -240,6 +252,13 @@ **AllowShortCaseLabelsOnASingleLine** (``bool``) If ``true``, short case labels will be contracted to a single line. + .. code-block:: c++ + + switch (a) { + case 1: x = 1; break; + case 2: return; + } + **AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``) Dependent on the value, ``int f() { return 0; }`` can be put on a single line. @@ -316,10 +335,21 @@ the string at that point leads to it being indented ``ContinuationIndentWidth`` spaces from the start of the line. + .. code-block:: c++ + + aaaa = + "bbbb" + "cccc"; + **AlwaysBreakTemplateDeclarations** (``bool``) If ``true``, always break after the ``template<...>`` of a template declaration. + .. code-block:: c++ + + template + class C {}; + **BinPackArguments** (``bool``) If ``false``, a function call's arguments will either be all on the same line or will have one line each. @@ -411,6 +441,13 @@ Always break constructor initializers before commas and align the commas with the colon. + .. code-block:: c++ + + SomeClass::Constructor() + : a(a) + , b(b) + , c(c) {} + **BreakStringLiterals** (``bool``) Allow breaking string literals when formatting. @@ -475,6 +512,10 @@ If ``true``, clang-format adds missing namespace end comments and fixes invalid existing ones. + .. code-block:: c++ + + namespace a {} // namespace a; + **ForEachMacros** (``std::vector``) A vector of macros that should be interpreted as foreach loops instead of as function calls. @@ -683,9 +724,18 @@ **SpaceAfterTemplateKeyword** (``bool``) If ``true``, a space will be inserted after the 'template' keyword. + .. code-block:: c++ + + template void foo(); + **SpaceBeforeAssignmentOperators** (``bool``) If ``false``, spaces will be removed before assignment operators. + .. code-block:: c++ + + int a = 5; + a += 42 + **SpaceBeforeParens** (``SpaceBeforeParensOptions``) Defines in which cases to put a space before opening parentheses. @@ -721,9 +771,18 @@ If ``true``, spaces will be inserted after ``<`` and before ``>`` in template argument lists. + .. code-block:: c++ + + static_cast< int >(arg); + std::function< void(int, int) > fct; + **SpacesInCStyleCastParentheses** (``bool``) If ``true``, spaces may be inserted into C style casts. + .. code-block:: c++ + + x = ( int32 )y + **SpacesInContainerLiterals** (``bool``) If ``true``, spaces are inserted inside container literals (e.g. ObjC and Javascript array and dict literals). @@ -731,9 +790,19 @@ **SpacesInParentheses** (``bool``) If ``true``, spaces will be inserted after ``(`` and before ``)``. + .. code-block:: c++ + + SomeType MemberFunction( const Deleted & ) & = delete; + **SpacesInSquareBrackets** (``bool``) If ``true``, spaces will be inserted after ``[`` and before ``]``. + Lambdas or unspecified size array declarations will not be updated. + .. code-block:: c++ + + int a[ 5 ]; + std::unique_ptr foo() {} // Won't be updated + **Standard** (``LanguageStandard``) Format compatible with this standard, e.g. use ``A >`` instead of ``A>`` for ``LS_Cpp03``. Index: include/clang/Format/Format.h =================================================================== --- include/clang/Format/Format.h +++ include/clang/Format/Format.h @@ -100,6 +100,12 @@ /// \brief If ``true``, aligns escaped newlines as far left as possible. /// Otherwise puts them into the right-most column. + /// \code + /// #define A \ + /// int aaaa; \ + /// int b; \ + /// int dddddddddd; + /// \endcode bool AlignEscapedNewlinesLeft; /// \brief If ``true``, horizontally align operands of binary and ternary @@ -114,6 +120,10 @@ bool AlignOperands; /// \brief If ``true``, aligns trailing comments. + /// \code + /// int a; // My comment about a + /// int b = 2; // comment about b + /// \endcode bool AlignTrailingComments; /// \brief Allow putting all parameters of a function declaration onto @@ -126,6 +136,12 @@ bool AllowShortBlocksOnASingleLine; /// \brief If ``true``, short case labels will be contracted to a single line. + /// \code + /// switch (a) { + /// case 1: x = 1; break; + /// case 2: return; + /// } + /// \endcode bool AllowShortCaseLabelsOnASingleLine; /// \brief Different styles for merging short functions containing at most one @@ -192,10 +208,19 @@ /// in a file look more consistent. Thus, it will only take effect if wrapping /// the string at that point leads to it being indented /// ``ContinuationIndentWidth`` spaces from the start of the line. + /// \code + /// aaaa = + /// "bbbb" + /// "cccc"; + /// \endcode bool AlwaysBreakBeforeMultilineStrings; /// \brief If ``true``, always break after the ``template<...>`` of a template /// declaration. + /// \code + /// template + /// class C {}; + /// \endcode bool AlwaysBreakTemplateDeclarations; /// \brief If ``false``, a function call's arguments will either be all on the @@ -284,6 +309,12 @@ /// \brief Always break constructor initializers before commas and align /// the commas with the colon. + /// \code + /// SomeClass::Constructor() + /// : a(a) + /// , b(b) + /// , c(c) {} + /// \endcode bool BreakConstructorInitializersBeforeComma; /// \brief Break after each annotation on a field in Java files. @@ -351,6 +382,11 @@ /// \brief If ``true``, clang-format adds missing namespace end comments and /// fixes invalid existing ones. + /// \code + /// namespace a { + /// foo(); + /// } // namespace a; + /// \endcode bool FixNamespaceComments; /// \brief A vector of macros that should be interpreted as foreach loops @@ -557,9 +593,16 @@ bool SpaceAfterCStyleCast; /// \brief If \c true, a space will be inserted after the 'template' keyword. + /// \code + /// template void foo(); + /// \endcode bool SpaceAfterTemplateKeyword; /// \brief If ``false``, spaces will be removed before assignment operators. + /// \code + /// int a = 5; + /// a += 42 + /// \endcode bool SpaceBeforeAssignmentOperators; /// \brief Different ways to put a space before opening parentheses. @@ -592,6 +635,10 @@ /// \brief If ``true``, spaces will be inserted after ``<`` and before ``>`` /// in template argument lists. + /// \code + /// static_cast< int >(arg); + /// std::function< void(int, int) > fct; + /// \endcode bool SpacesInAngles; /// \brief If ``true``, spaces are inserted inside container literals (e.g. @@ -599,12 +646,23 @@ bool SpacesInContainerLiterals; /// \brief If ``true``, spaces may be inserted into C style casts. + /// \code + /// x = ( int32 )y + /// \endcode bool SpacesInCStyleCastParentheses; /// \brief If ``true``, spaces will be inserted after ``(`` and before ``)``. + /// \code + /// SomeType MemberFunction( const Deleted & ) & = delete; + /// \endcode bool SpacesInParentheses; /// \brief If ``true``, spaces will be inserted after ``[`` and before ``]``. + /// Lambdas or unspecified size array declarations will not be updated. + /// \code + /// int a[ 5 ]; + /// std::unique_ptr foo() {} // Won't be updated + /// \endcode bool SpacesInSquareBrackets; /// \brief Supported language standards.