Index: docs/ClangFormatStyleOptions.rst =================================================================== --- docs/ClangFormatStyleOptions.rst +++ docs/ClangFormatStyleOptions.rst @@ -641,6 +641,13 @@ **BreakAfterJavaFieldAnnotations** (``bool``) Break after each annotation on a field in Java files. + .. code-block:: java + + true: false: + @Partial vs. @Partial @Mock DataLoad loader; + @Mock + DataLoad loader; + **BreakBeforeBinaryOperators** (``BinaryOperatorStyle``) The way to wrap binary operators. @@ -928,6 +935,14 @@ **ContinuationIndentWidth** (``unsigned``) Indent width for line continuations. + .. code-block:: c++ + + ContinuationIndentWidth: 2 + + int i = // VeryVeryVeryVeryVeryLongComment + longFunction( // Again a long comment + arg); + **Cpp11BracedListStyle** (``bool``) If ``true``, format braced lists as best suited for C++11 braced lists. @@ -943,10 +958,20 @@ the parentheses of a function call with that name. If there is no name, a zero-length name is assumed. + .. code-block:: c++ + + true: false: + vector x{1, 2, 3, 4}; vs. vector x{ 1, 2, 3, 4 }; + vector x{{}, {}, {}, {}}; vector x{ {}, {}, {}, {} }; + f(MyMap[{composite, key}]); f(MyMap[{ composite, key }]); + new int[3]{1, 2, 3}; new int[3]{ 1, 2, 3 }; + **DerivePointerAlignment** (``bool``) If ``true``, analyze the formatted file for the most common - alignment of ``&`` and ``*``. ``PointerAlignment`` is then used only as - fallback. + alignment of ``&`` and ``*``. + Pointer and reference alignment styles are going to be updated according + to the preferences found in the file. + ``PointerAlignment`` is then used only as fallback. **DisableFormat** (``bool``) Disables formatting completely. @@ -1041,6 +1066,17 @@ When ``false``, use the same indentation level as for the switch statement. Switch statement body is always indented one level more than case labels. + .. code-block:: c++ + + false: true: + switch (fool) { vs. switch (fool) { + case 1: case 1: + bar(); bar(); + break; break; + default: default: + plop(); plop(); + } } + **IndentWidth** (``unsigned``) The number of columns to use for indentation. @@ -1047,6 +1083,7 @@ .. code-block:: c++ IndentWidth: 3 + void f() { someFunction(); if (true, false) { @@ -1058,6 +1095,16 @@ Indent if a function definition or declaration is wrapped after the type. + .. code-block:: c++ + + true: + LoooooooooooooooooooooooooooooooooooooooongReturnType + LoooooooooooooooooooooooooooooooongFunctionDeclaration(); + + false: + LoooooooooooooooooooooooooooooooooooooooongReturnType + LoooooooooooooooooooooooooooooooongFunctionDeclaration(); + **JavaScriptQuotes** (``JavaScriptQuoteStyle``) The JavaScriptQuoteStyle to use for JavaScript strings. @@ -1105,8 +1152,16 @@ import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js" **KeepEmptyLinesAtTheStartOfBlocks** (``bool``) - If true, empty lines at the start of blocks are kept. + If true, the empty line at the start of blocks is kept. + .. code-block:: c++ + + true: false: + if (foo) { vs. if (foo) { + bar(); + bar(); } + } + **Language** (``LanguageKind``) Language, this format style is targeted at. @@ -1228,6 +1283,14 @@ **ObjCBlockIndentWidth** (``unsigned``) The number of characters to use for indentation of ObjC blocks. + .. code-block:: objc + + ObjCBlockIndentWidth: 4 + + [operation setCompletionBlock:^{ + [self onOperationDone]; + }]; + **ObjCSpaceAfterProperty** (``bool``) Add a space after ``@property`` in Objective-C, i.e. use ``@property (readonly)`` instead of ``@property(readonly)``. Index: include/clang/Format/Format.h =================================================================== --- include/clang/Format/Format.h +++ include/clang/Format/Format.h @@ -177,7 +177,7 @@ SFS_Empty, /// \brief Only merge functions defined inside a class. Implies "empty". /// \code - /// class { + /// class Foo { /// void f() { foo(); } /// }; /// \endcode @@ -184,7 +184,7 @@ SFS_Inline, /// \brief Merge all functions fitting on a single line. /// \code - /// class { + /// class Foo { /// void f() { foo(); } /// }; /// void f() { bar(); } @@ -705,6 +705,12 @@ bool BreakConstructorInitializersBeforeComma; /// \brief Break after each annotation on a field in Java files. + /// \code{.java} + /// true: false: + /// @Partial vs. @Partial @Mock DataLoad loader; + /// @Mock + /// DataLoad loader; + /// \endcode bool BreakAfterJavaFieldAnnotations; /// \brief Allow breaking string literals when formatting. @@ -720,7 +726,7 @@ /// \brief A regular expression that describes comments with special meaning, /// which should not be split into lines or otherwise changed. /// \code - /// CommentPragmas: '^ FOOBAR pragma:' + /// // CommentPragmas: '^ FOOBAR pragma:' /// // Will leave the following line unaffected /// #include // FOOBAR pragma: keep /// \endcode @@ -760,6 +766,13 @@ unsigned ConstructorInitializerIndentWidth; /// \brief Indent width for line continuations. + /// \code + /// ContinuationIndentWidth: 2 + /// + /// int i = // VeryVeryVeryVeryVeryLongComment + /// longFunction( // Again a long comment + /// arg); + /// \endcode unsigned ContinuationIndentWidth; /// \brief If ``true``, format braced lists as best suited for C++11 braced @@ -775,11 +788,20 @@ /// (e.g. a type or variable name), clang-format formats as if the ``{}`` were /// the parentheses of a function call with that name. If there is no name, /// a zero-length name is assumed. + /// \code + /// true: false: + /// vector x{1, 2, 3, 4}; vs. vector x{ 1, 2, 3, 4 }; + /// vector x{{}, {}, {}, {}}; vector x{ {}, {}, {}, {} }; + /// f(MyMap[{composite, key}]); f(MyMap[{ composite, key }]); + /// new int[3]{1, 2, 3}; new int[3]{ 1, 2, 3 }; + /// \endcode bool Cpp11BracedListStyle; /// \brief If ``true``, analyze the formatted file for the most common - /// alignment of ``&`` and ``*``. ``PointerAlignment`` is then used only as - /// fallback. + /// alignment of ``&`` and ``*``. + /// Pointer and reference alignment styles are going to be updated according + /// to the preferences found in the file. + /// ``PointerAlignment`` is then used only as fallback. bool DerivePointerAlignment; /// \brief Disables formatting completely. @@ -880,11 +902,22 @@ /// /// When ``false``, use the same indentation level as for the switch statement. /// Switch statement body is always indented one level more than case labels. + /// \code + /// false: true: + /// switch (fool) { vs. switch (fool) { + /// case 1: case 1: + /// bar(); bar(); + /// break; break; + /// default: default: + /// plop(); plop(); + /// } } + /// \endcode bool IndentCaseLabels; /// \brief The number of columns to use for indentation. /// \code /// IndentWidth: 3 + /// /// void f() { /// someFunction(); /// if (true, false) { @@ -896,6 +929,15 @@ /// \brief Indent if a function definition or declaration is wrapped after the /// type. + /// \code + /// true: + /// LoooooooooooooooooooooooooooooooooooooooongReturnType + /// LoooooooooooooooooooooooooooooooongFunctionDeclaration(); + /// + /// false: + /// LoooooooooooooooooooooooooooooooooooooooongReturnType + /// LoooooooooooooooooooooooooooooooongFunctionDeclaration(); + /// \endcode bool IndentWrappedFunctionNames; /// \brief Quotation styles for JavaScript strings. Does not affect template @@ -938,7 +980,14 @@ /// \endcode bool JavaScriptWrapImports; - /// \brief If true, empty lines at the start of blocks are kept. + /// \brief If true, the empty line at the start of blocks is kept. + /// \code + /// true: false: + /// if (foo) { vs. if (foo) { + /// bar(); + /// bar(); } + /// } + /// \endcode bool KeepEmptyLinesAtTheStartOfBlocks; /// \brief Supported languages. @@ -1050,6 +1099,13 @@ NamespaceIndentationKind NamespaceIndentation; /// \brief The number of characters to use for indentation of ObjC blocks. + /// \code{.objc} + /// ObjCBlockIndentWidth: 4 + /// + /// [operation setCompletionBlock:^{ + /// [self onOperationDone]; + /// }]; + /// \endcode unsigned ObjCBlockIndentWidth; /// \brief Add a space after ``@property`` in Objective-C, i.e. use