aboutsummaryrefslogtreecommitdiff
path: root/docs/ClangFormatStyleOptions.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/ClangFormatStyleOptions.rst')
-rw-r--r--docs/ClangFormatStyleOptions.rst812
1 files changed, 803 insertions, 9 deletions
diff --git a/docs/ClangFormatStyleOptions.rst b/docs/ClangFormatStyleOptions.rst
index 3f76da6dca32..ed628e370087 100644
--- a/docs/ClangFormatStyleOptions.rst
+++ b/docs/ClangFormatStyleOptions.rst
@@ -213,6 +213,20 @@ the configuration (without a prefix: ``Auto``).
If ``true``, aligns escaped newlines as far left as possible.
Otherwise puts them into the right-most column.
+ .. code-block:: c++
+
+ true:
+ #define A \
+ int aaaa; \
+ int b; \
+ int dddddddddd;
+
+ false:
+ #define A \
+ int aaaa; \
+ int b; \
+ int dddddddddd;
+
**AlignOperands** (``bool``)
If ``true``, horizontally align operands of binary and ternary
expressions.
@@ -228,10 +242,23 @@ the configuration (without a prefix: ``Auto``).
**AlignTrailingComments** (``bool``)
If ``true``, aligns trailing comments.
+ .. code-block:: c++
+
+ true: false:
+ int a; // My comment a vs. int a; // My comment a
+ int b = 2; // comment b 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``.
+ .. code-block:: c++
+
+ true: false:
+ myFunction(foo, vs. myFunction(foo, bar, plop);
+ bar,
+ plop);
+
**AllowShortBlocksOnASingleLine** (``bool``)
Allows contracting simple braced statements to a single line.
@@ -240,6 +267,17 @@ the configuration (without a prefix: ``Auto``).
**AllowShortCaseLabelsOnASingleLine** (``bool``)
If ``true``, short case labels will be contracted to a single line.
+ .. code-block:: c++
+
+ true: false:
+ switch (a) { vs. switch (a) {
+ case 1: x = 1; break; case 1:
+ case 2: return; x = 1;
+ } break;
+ case 2:
+ return;
+ }
+
**AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``)
Dependent on the value, ``int f() { return 0; }`` can be put on a
single line.
@@ -252,12 +290,32 @@ the configuration (without a prefix: ``Auto``).
* ``SFS_Empty`` (in configuration: ``Empty``)
Only merge empty functions.
+ .. code-block:: c++
+
+ void f() { bar(); }
+ void f2() {
+ bar2();
+ }
+
* ``SFS_Inline`` (in configuration: ``Inline``)
Only merge functions defined inside a class. Implies "empty".
+ .. code-block:: c++
+
+ class Foo {
+ void f() { foo(); }
+ };
+
* ``SFS_All`` (in configuration: ``All``)
Merge all functions fitting on a single line.
+ .. code-block:: c++
+
+ class Foo {
+ void f() { foo(); }
+ };
+ void f() { bar(); }
+
**AllowShortIfStatementsOnASingleLine** (``bool``)
@@ -269,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:
@@ -294,18 +352,78 @@ the configuration (without a prefix: ``Auto``).
Break after return type automatically.
``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
+ .. code-block:: c++
+
+ class A {
+ int f() { return 0; };
+ };
+ int f();
+ int f() { return 1; }
+
* ``RTBS_All`` (in configuration: ``All``)
Always break after the return type.
+ .. code-block:: c++
+
+ class A {
+ int
+ f() {
+ return 0;
+ };
+ };
+ int
+ f();
+ int
+ f() {
+ return 1;
+ }
+
* ``RTBS_TopLevel`` (in configuration: ``TopLevel``)
Always break after the return types of top-level functions.
+ .. code-block:: c++
+
+ class A {
+ int f() { return 0; };
+ };
+ int
+ f();
+ int
+ f() {
+ return 1;
+ }
+
* ``RTBS_AllDefinitions`` (in configuration: ``AllDefinitions``)
Always break after the return type of function definitions.
+ .. code-block:: c++
+
+ class A {
+ int
+ f() {
+ return 0;
+ };
+ };
+ int f();
+ int
+ f() {
+ return 1;
+ }
+
* ``RTBS_TopLevelDefinitions`` (in configuration: ``TopLevelDefinitions``)
Always break after the return type of top-level definitions.
+ .. code-block:: c++
+
+ class A {
+ int f() { return 0; };
+ };
+ int f();
+ int
+ f() {
+ return 1;
+ }
+
**AlwaysBreakBeforeMultilineStrings** (``bool``)
@@ -316,18 +434,57 @@ the configuration (without a prefix: ``Auto``).
the string at that point leads to it being indented
``ContinuationIndentWidth`` spaces from the start of the line.
+ .. code-block:: c++
+
+ true: false:
+ aaaa = vs. aaaa = "bbbb"
+ "bbbb" "cccc";
+ "cccc";
+
**AlwaysBreakTemplateDeclarations** (``bool``)
If ``true``, always break after the ``template<...>`` of a template
declaration.
+ .. code-block:: c++
+
+ true: false:
+ template <typename T> vs. template <typename T> class C {};
+ 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.
+ .. 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.
@@ -336,22 +493,161 @@ the configuration (without a prefix: ``Auto``).
Nested configuration flags:
+
* ``bool AfterClass`` Wrap class definitions.
+
+ .. code-block:: c++
+
+ true:
+ class foo {};
+
+ false:
+ class foo
+ {};
+
* ``bool AfterControlStatement`` Wrap control statements (``if``/``for``/``while``/``switch``/..).
+
+ .. code-block:: c++
+
+ true:
+ if (foo())
+ {
+ } else
+ {}
+ for (int i = 0; i < 10; ++i)
+ {}
+
+ false:
+ if (foo()) {
+ } else {
+ }
+ for (int i = 0; i < 10; ++i) {
+ }
+
* ``bool AfterEnum`` Wrap enum definitions.
+
+ .. code-block:: c++
+
+ true:
+ enum X : int
+ {
+ B
+ };
+
+ false:
+ enum X : int { B };
+
* ``bool AfterFunction`` Wrap function definitions.
+
+ .. code-block:: c++
+
+ true:
+ void foo()
+ {
+ bar();
+ bar2();
+ }
+
+ false:
+ void foo() {
+ bar();
+ bar2();
+ }
+
* ``bool AfterNamespace`` Wrap namespace definitions.
+
+ .. code-block:: c++
+
+ true:
+ namespace
+ {
+ int foo();
+ int bar();
+ }
+
+ false:
+ namespace {
+ int foo();
+ int bar();
+ }
+
* ``bool AfterObjCDeclaration`` Wrap ObjC definitions (``@autoreleasepool``, interfaces, ..).
+
* ``bool AfterStruct`` Wrap struct definitions.
+
+ .. code-block:: c++
+
+ true:
+ struct foo
+ {
+ int x;
+ }
+
+ false:
+ struct foo {
+ int x;
+ }
+
* ``bool AfterUnion`` Wrap union definitions.
+
+ .. code-block:: c++
+
+ true:
+ union foo
+ {
+ int x;
+ }
+
+ false:
+ union foo {
+ int x;
+ }
+
* ``bool BeforeCatch`` Wrap before ``catch``.
+
+ .. code-block:: c++
+
+ true:
+ try {
+ foo();
+ }
+ catch () {
+ }
+
+ false:
+ try {
+ foo();
+ } catch () {
+ }
+
* ``bool BeforeElse`` Wrap before ``else``.
+
+ .. code-block:: c++
+
+ true:
+ if (foo()) {
+ }
+ else {
+ }
+
+ false:
+ if (foo()) {
+ } else {
+ }
+
* ``bool IndentBraces`` Indent the wrapped braces themselves.
**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.
@@ -360,12 +656,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``)
@@ -376,41 +705,190 @@ the configuration (without a prefix: ``Auto``).
* ``BS_Attach`` (in configuration: ``Attach``)
Always attach braces to surrounding context.
+ .. code-block:: c++
+
+ try {
+ foo();
+ } catch () {
+ }
+ void foo() { bar(); }
+ class foo {};
+ if (foo()) {
+ } else {
+ }
+ enum X : int { A, B };
+
* ``BS_Linux`` (in configuration: ``Linux``)
Like ``Attach``, but break before braces on function, namespace and
class definitions.
+ .. code-block:: c++
+
+ try {
+ foo();
+ } catch () {
+ }
+ void foo() { bar(); }
+ class foo
+ {
+ };
+ if (foo()) {
+ } else {
+ }
+ enum X : int { A, B };
+
* ``BS_Mozilla`` (in configuration: ``Mozilla``)
Like ``Attach``, but break before braces on enum, function, and record
definitions.
+ .. code-block:: c++
+
+ try {
+ foo();
+ } catch () {
+ }
+ void foo() { bar(); }
+ class foo
+ {
+ };
+ if (foo()) {
+ } else {
+ }
+ enum X : int { A, B };
+
* ``BS_Stroustrup`` (in configuration: ``Stroustrup``)
Like ``Attach``, but break before function definitions, ``catch``, and
``else``.
+ .. code-block:: c++
+
+ try {
+ foo();
+ } catch () {
+ }
+ void foo() { bar(); }
+ class foo
+ {
+ };
+ if (foo()) {
+ } else {
+ }
+ enum X : int
+ {
+ A,
+ B
+ };
+
* ``BS_Allman`` (in configuration: ``Allman``)
Always break before braces.
+ .. code-block:: c++
+
+ try {
+ foo();
+ }
+ catch () {
+ }
+ void foo() { bar(); }
+ class foo {
+ };
+ if (foo()) {
+ }
+ else {
+ }
+ enum X : int { A, B };
+
* ``BS_GNU`` (in configuration: ``GNU``)
Always break before braces and add an extra level of indentation to
braces of control statements, not to those of class, function
or other definitions.
+ .. code-block:: c++
+
+ try
+ {
+ foo();
+ }
+ catch ()
+ {
+ }
+ void foo() { bar(); }
+ class foo
+ {
+ };
+ if (foo())
+ {
+ }
+ else
+ {
+ }
+ enum X : int
+ {
+ A,
+ B
+ };
+
* ``BS_WebKit`` (in configuration: ``WebKit``)
Like ``Attach``, but break before functions.
+ .. code-block:: c++
+
+ try {
+ foo();
+ } catch () {
+ }
+ void foo() { bar(); }
+ class foo {
+ };
+ if (foo()) {
+ } else {
+ }
+ enum X : int { A, B };
+
* ``BS_Custom`` (in configuration: ``Custom``)
Configure each individual brace in `BraceWrapping`.
+**BreakBeforeInheritanceComma** (``bool``)
+ If ``true``, in the class inheritance expression clang-format will
+ break before ``:`` and ``,`` if there is multiple inheritance.
+
+ .. code-block:: c++
+
+ true: false:
+ class MyClass vs. class MyClass : public X, public Y {
+ : public X };
+ , public Y {
+ };
+
**BreakBeforeTernaryOperators** (``bool``)
If ``true``, ternary operators will be placed after line breaks.
+ .. code-block:: c++
+
+ true:
+ veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription
+ ? firstValue
+ : SecondValueVeryVeryVeryVeryLong;
+
+ true:
+ veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription ?
+ firstValue :
+ SecondValueVeryVeryVeryVeryLong;
+
**BreakConstructorInitializersBeforeComma** (``bool``)
Always break constructor initializers before commas and align
the commas with the colon.
+ .. code-block:: c++
+
+ true: false:
+ SomeClass::Constructor() vs. SomeClass::Constructor() : a(a),
+ : a(a) b(b),
+ , b(b) c(c) {}
+ , c(c) {}
+
**BreakStringLiterals** (``bool``)
Allow breaking string literals when formatting.
@@ -425,10 +903,31 @@ 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 <vector> // FOOBAR pragma: keep
+
**ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``)
If the constructor initializers don't fit on a line, put each
initializer on its own line.
+ .. code-block:: c++
+
+ true:
+ SomeClass::Constructor()
+ : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) {
+ return 0;
+ }
+
+ false:
+ SomeClass::Constructor()
+ : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa),
+ aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) {
+ return 0;
+ }
+
**ConstructorInitializerIndentWidth** (``unsigned``)
The number of characters to use for indentation of constructor
initializer lists.
@@ -436,6 +935,14 @@ the configuration (without a prefix: ``Auto``).
**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.
@@ -451,10 +958,20 @@ the configuration (without a prefix: ``Auto``).
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<int> x{1, 2, 3, 4}; vs. vector<int> x{ 1, 2, 3, 4 };
+ vector<T> x{{}, {}, {}, {}}; vector<T> 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.
@@ -471,6 +988,17 @@ the configuration (without a prefix: ``Auto``).
NOTE: This is an experimental flag, that might go away or be renamed. Do
not use this in config files, etc. Use at your own risk.
+**FixNamespaceComments** (``bool``)
+ If ``true``, clang-format adds missing namespace end comments and
+ fixes invalid existing ones.
+
+ .. code-block:: c++
+
+ true: false:
+ namespace a { vs. namespace a {
+ foo(); foo();
+ } // namespace a; }
+
**ForEachMacros** (``std::vector<std::string>``)
A vector of macros that should be interpreted as foreach loops
instead of as function calls.
@@ -516,7 +1044,7 @@ the configuration (without a prefix: ``Auto``).
Priority: 2
- Regex: '^(<|"(gtest|isl|json)/)'
Priority: 3
- - Regex: '.\*'
+ - Regex: '.*'
Priority: 1
**IncludeIsMainRegex** (``std::string``)
@@ -538,13 +1066,45 @@ the configuration (without a prefix: ``Auto``).
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.
+ .. 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.
+ .. code-block:: c++
+
+ true:
+ LoooooooooooooooooooooooooooooooooooooooongReturnType
+ LoooooooooooooooooooooooooooooooongFunctionDeclaration();
+
+ false:
+ LoooooooooooooooooooooooooooooooooooooooongReturnType
+ LoooooooooooooooooooooooooooooooongFunctionDeclaration();
+
**JavaScriptQuotes** (``JavaScriptQuoteStyle``)
The JavaScriptQuoteStyle to use for JavaScript strings.
@@ -553,16 +1113,54 @@ 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.
+ 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.
@@ -573,7 +1171,7 @@ the configuration (without a prefix: ``Auto``).
Do not use.
* ``LK_Cpp`` (in configuration: ``Cpp``)
- Should be used for C, C++, ObjectiveC, ObjectiveC++.
+ Should be used for C, C++.
* ``LK_Java`` (in configuration: ``Java``)
Should be used for Java.
@@ -581,6 +1179,9 @@ the configuration (without a prefix: ``Auto``).
* ``LK_JavaScript`` (in configuration: ``JavaScript``)
Should be used for JavaScript.
+ * ``LK_ObjC`` (in configuration: ``ObjC``)
+ Should be used for Objective-C, Objective-C++.
+
* ``LK_Proto`` (in configuration: ``Proto``)
Should be used for Protocol Buffers
(https://developers.google.com/protocol-buffers/).
@@ -593,12 +1194,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.
@@ -607,17 +1245,52 @@ 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``)
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)``.
@@ -653,29 +1326,75 @@ the configuration (without a prefix: ``Auto``).
* ``PAS_Left`` (in configuration: ``Left``)
Align pointer to the left.
+ .. code-block:: c++
+
+ int* a;
+
* ``PAS_Right`` (in configuration: ``Right``)
Align pointer to the right.
+ .. code-block:: c++
+
+ int *a;
+
* ``PAS_Middle`` (in configuration: ``Middle``)
Align pointer in the middle.
+ .. code-block:: c++
+
+ int * a;
+
**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``.
+ .. code-block:: c++
+
+ false: true:
+ #include "b.h" vs. #include "a.h"
+ #include "a.h" #include "b.h"
+
**SpaceAfterCStyleCast** (``bool``)
- If ``true``, a space may be inserted after C style casts.
+ If ``true``, a space is inserted after C style casts.
+
+ .. code-block:: c++
+
+ true: false:
+ (int)i; vs. (int) i;
**SpaceAfterTemplateKeyword** (``bool``)
If ``true``, a space will be inserted after the 'template' keyword.
+ .. code-block:: c++
+
+ true: false:
+ template <int> void foo(); vs. template<int> void foo();
+
**SpaceBeforeAssignmentOperators** (``bool``)
If ``false``, spaces will be removed before assignment operators.
+ .. code-block:: c++
+
+ true: false:
+ int a = 5; vs. int a=5;
+ a += 42 a+=42;
+
**SpaceBeforeParens** (``SpaceBeforeParensOptions``)
Defines in which cases to put a space before opening parentheses.
@@ -684,21 +1403,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).
@@ -707,22 +1460,60 @@ 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.
+ .. code-block:: c++
+
+ true: false:
+ static_cast< int >(arg); vs. static_cast<int>(arg);
+ std::function< void(int) > fct; std::function<void(int)> fct;
+
**SpacesInCStyleCastParentheses** (``bool``)
If ``true``, spaces may be inserted into C style casts.
+ .. code-block:: c++
+
+ true: false:
+ x = ( int32 )y vs. x = (int32)y
+
**SpacesInContainerLiterals** (``bool``)
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 ``)``.
+ .. code-block:: c++
+
+ true: false:
+ t f( Deleted & ) & = delete; vs. t f(Deleted &) & = delete;
+
**SpacesInSquareBrackets** (``bool``)
If ``true``, spaces will be inserted after ``[`` and before ``]``.
+ Lambdas or unspecified size array declarations will not be affected.
+
+ .. code-block:: c++
+
+ true: false:
+ int a[ 5 ]; vs. int a[5];
+ std::unique_ptr<int[]> foo() {} // Won't be affected
**Standard** (``LanguageStandard``)
Format compatible with this standard, e.g. use ``A<A<int> >``
@@ -734,7 +1525,8 @@ the configuration (without a prefix: ``Auto``).
Use C++03-compatible syntax.
* ``LS_Cpp11`` (in configuration: ``Cpp11``)
- Use features of C++11 (e.g. ``A<A<int>>`` instead of ``A<A<int> >``).
+ Use features of C++11, C++14 and C++1z (e.g. ``A<A<int>>`` instead of
+ ``A<A<int> >``).
* ``LS_Auto`` (in configuration: ``Auto``)
Automatic detection based on the input.
@@ -755,6 +1547,9 @@ the configuration (without a prefix: ``Auto``).
* ``UT_ForIndentation`` (in configuration: ``ForIndentation``)
Use tabs only for indentation.
+ * ``UT_ForContinuationAndIndentation`` (in configuration: ``ForContinuationAndIndentation``)
+ Use tabs only for line continuation and indentation.
+
* ``UT_Always`` (in configuration: ``Always``)
Use tabs whenever we need to fill whitespace that spans at least from
one tab stop to the next one.
@@ -872,4 +1667,3 @@ The result is:
r();
}
}
-
generated by cgit v1.2.3 (git 2.25.1) at 2024-05-07 05:12:27 +0000