OSchip
/
llvm-project
mirror of https://github.com/THU-DSP-LAB/llvm-project.git
13
0
Fork 6
Code Issues Packages Projects Releases Wiki Activity

[clang-format][docs] Fix documentation of clang-format BasedOnStyle type 

Fix little inconsistency and use `std::string` (which is used everywhere
else) instead of `string`

Reviewed By: MyDeveloperDay, HazardyKnusperkeks

Differential Revision: https://reviews.llvm.org/D108765
This commit is contained in:
Ludovic Jozeau 2021-09-24 08:14:53 +01:00 committed by mydeveloperday
parent 87ab958641
commit 9e8fff26f3
3 changed files with 156 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

182
clang/docs/ClangFormatStyleOptions.rst
View File

@ -125,7 +125,7 @@ enumeration member (with a prefix, e.g. ``LS_Auto``), and as a value usable in
the configuration (without a prefix: ``Auto``). the configuration (without a prefix: ``Auto``).
**BasedOnStyle** (``string``) **BasedOnStyle** (``String``)
The style used for all options not specifically set in the configuration. The style used for all options not specifically set in the configuration.
This option is supported only in the :program:`clang-format` configuration This option is supported only in the :program:`clang-format` configuration
@ -166,7 +166,7 @@ the configuration (without a prefix: ``Auto``).
.. START_FORMAT_STYLE_OPTIONS .. START_FORMAT_STYLE_OPTIONS
**AccessModifierOffset** (``int``) **AccessModifierOffset** (``Integer``)
The extra indent or outdent of access modifiers, e.g. ``public:``. The extra indent or outdent of access modifiers, e.g. ``public:``.
**AlignAfterOpenBracket** (``BracketAlignmentStyle``) **AlignAfterOpenBracket** (``BracketAlignmentStyle``)
@ -619,7 +619,7 @@ the configuration (without a prefix: ``Auto``).
**AlignTrailingComments** (``bool``) **AlignTrailingComments** (``Boolean``)
If ``true``, aligns trailing comments. If ``true``, aligns trailing comments.
.. code-block:: c++ .. code-block:: c++
@ -628,7 +628,7 @@ the configuration (without a prefix: ``Auto``).
int a; // My comment a vs. int a; // My comment a int a; // My comment a vs. int a; // My comment a
int b = 2; // comment b int b = 2; // comment about b int b = 2; // comment b int b = 2; // comment about b
**AllowAllArgumentsOnNextLine** (``bool``) **AllowAllArgumentsOnNextLine** (``Boolean``)
If a function call or braced initializer list doesn't fit on a If a function call or braced initializer list doesn't fit on a
line, allow putting all arguments onto the next line, even if line, allow putting all arguments onto the next line, even if
``BinPackArguments`` is ``false``. ``BinPackArguments`` is ``false``.
@ -645,11 +645,11 @@ the configuration (without a prefix: ``Auto``).
c, c,
d); d);
**AllowAllConstructorInitializersOnNextLine** (``bool``) **AllowAllConstructorInitializersOnNextLine** (``Boolean``)
This option is **deprecated**. See ``NextLine`` of This option is **deprecated**. See ``NextLine`` of
``PackConstructorInitializers``. ``PackConstructorInitializers``.
**AllowAllParametersOfDeclarationOnNextLine** (``bool``) **AllowAllParametersOfDeclarationOnNextLine** (``Boolean``)
If the function declaration doesn't fit on a line, If the function declaration doesn't fit on a line,
allow putting all parameters of a function declaration onto allow putting all parameters of a function declaration onto
the next line even if ``BinPackParameters`` is ``false``. the next line even if ``BinPackParameters`` is ``false``.
@ -704,7 +704,7 @@ the configuration (without a prefix: ``Auto``).
**AllowShortCaseLabelsOnASingleLine** (``bool``) **AllowShortCaseLabelsOnASingleLine** (``Boolean``)
If ``true``, short case labels will be contracted to a single line. If ``true``, short case labels will be contracted to a single line.
.. code-block:: c++ .. code-block:: c++
@ -718,7 +718,7 @@ the configuration (without a prefix: ``Auto``).
return; return;
} }
**AllowShortEnumsOnASingleLine** (``bool``) **AllowShortEnumsOnASingleLine** (``Boolean``)
Allow short enums on a single line. Allow short enums on a single line.
.. code-block:: c++ .. code-block:: c++
@ -909,7 +909,7 @@ the configuration (without a prefix: ``Auto``).
**AllowShortLoopsOnASingleLine** (``bool``) **AllowShortLoopsOnASingleLine** (``Boolean``)
If ``true``, ``while (true) continue;`` can be put on a single If ``true``, ``while (true) continue;`` can be put on a single
line. line.
@ -1014,7 +1014,7 @@ the configuration (without a prefix: ``Auto``).
**AlwaysBreakBeforeMultilineStrings** (``bool``) **AlwaysBreakBeforeMultilineStrings** (``Boolean``)
If ``true``, always break before multiline string literals. If ``true``, always break before multiline string literals.
This flag is mean to make cases where there are multiple multiline strings This flag is mean to make cases where there are multiple multiline strings
@ -1074,7 +1074,7 @@ the configuration (without a prefix: ``Auto``).
**AttributeMacros** (``std::vector<std::string>``) **AttributeMacros** (``List of Strings``)
A vector of strings that should be interpreted as attributes/qualifiers A vector of strings that should be interpreted as attributes/qualifiers
instead of identifiers. This can be useful for language extensions or instead of identifiers. This can be useful for language extensions or
static analyzer annotations. static analyzer annotations.
@ -1093,7 +1093,7 @@ the configuration (without a prefix: ``Auto``).
AttributeMacros: ['__capability', '__output', '__ununsed'] AttributeMacros: ['__capability', '__output', '__ununsed']
**BinPackArguments** (``bool``) **BinPackArguments** (``Boolean``)
If ``false``, a function call's arguments will either be all on the If ``false``, a function call's arguments will either be all on the
same line or will have one line each. same line or will have one line each.
@ -1112,7 +1112,7 @@ the configuration (without a prefix: ``Auto``).
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa); aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
} }
**BinPackParameters** (``bool``) **BinPackParameters** (``Boolean``)
If ``false``, a function declaration's or function definition's 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. parameters will either all be on the same line or will have one line each.
@ -1450,7 +1450,7 @@ the configuration (without a prefix: ``Auto``).
} }
**BreakAfterJavaFieldAnnotations** (``bool``) **BreakAfterJavaFieldAnnotations** (``Boolean``)
Break after each annotation on a field in Java files. Break after each annotation on a field in Java files.
.. code-block:: java .. code-block:: java
@ -1960,7 +1960,7 @@ the configuration (without a prefix: ``Auto``).
**BreakBeforeConceptDeclarations** (``bool``) **BreakBeforeConceptDeclarations** (``Boolean``)
If ``true``, concept will be placed on a new line. If ``true``, concept will be placed on a new line.
.. code-block:: c++ .. code-block:: c++
@ -1972,7 +1972,7 @@ the configuration (without a prefix: ``Auto``).
false: false:
template<typename T> concept ... template<typename T> concept ...
**BreakBeforeTernaryOperators** (``bool``) **BreakBeforeTernaryOperators** (``Boolean``)
If ``true``, ternary operators will be placed after line breaks. If ``true``, ternary operators will be placed after line breaks.
.. code-block:: c++ .. code-block:: c++
@ -2069,7 +2069,7 @@ the configuration (without a prefix: ``Auto``).
**BreakStringLiterals** (``bool``) **BreakStringLiterals** (``Boolean``)
Allow breaking string literals when formatting. Allow breaking string literals when formatting.
.. code-block:: c++ .. code-block:: c++
@ -2083,14 +2083,14 @@ the configuration (without a prefix: ``Auto``).
const char* x = const char* x =
"veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString"; "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString";
**ColumnLimit** (``unsigned``) **ColumnLimit** (``Unsigned``)
The column limit. The column limit.
A column limit of ``0`` means that there is no column limit. In this case, A column limit of ``0`` means that there is no column limit. In this case,
clang-format will respect the input's line breaking decisions within clang-format will respect the input's line breaking decisions within
statements unless they contradict other rules. statements unless they contradict other rules.
**CommentPragmas** (``std::string``) **CommentPragmas** (``String``)
A regular expression that describes comments with special meaning, A regular expression that describes comments with special meaning,
which should not be split into lines or otherwise changed. which should not be split into lines or otherwise changed.
@ -2100,7 +2100,7 @@ the configuration (without a prefix: ``Auto``).
// Will leave the following line unaffected // Will leave the following line unaffected
#include <vector> // FOOBAR pragma: keep #include <vector> // FOOBAR pragma: keep
**CompactNamespaces** (``bool``) **CompactNamespaces** (``Boolean``)
If ``true``, consecutive namespace declarations will be on the same If ``true``, consecutive namespace declarations will be on the same
line. If ``false``, each namespace is declared on a new line. line. If ``false``, each namespace is declared on a new line.
@ -2125,15 +2125,15 @@ the configuration (without a prefix: ``Auto``).
namespace Extra { namespace Extra {
}}} }}}
**ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``) **ConstructorInitializerAllOnOneLineOrOnePerLine** (``Boolean``)
This option is **deprecated**. See ``CurrentLine`` of This option is **deprecated**. See ``CurrentLine`` of
``PackConstructorInitializers``. ``PackConstructorInitializers``.
**ConstructorInitializerIndentWidth** (``unsigned``) **ConstructorInitializerIndentWidth** (``Unsigned``)
The number of characters to use for indentation of constructor The number of characters to use for indentation of constructor
initializer lists as well as inheritance lists. initializer lists as well as inheritance lists.
**ContinuationIndentWidth** (``unsigned``) **ContinuationIndentWidth** (``Unsigned``)
Indent width for line continuations. Indent width for line continuations.
.. code-block:: c++ .. code-block:: c++
@ -2144,7 +2144,7 @@ the configuration (without a prefix: ``Auto``).
longFunction( // Again a long comment longFunction( // Again a long comment
arg); arg);
**Cpp11BracedListStyle** (``bool``) **Cpp11BracedListStyle** (``Boolean``)
If ``true``, format braced lists as best suited for C++11 braced If ``true``, format braced lists as best suited for C++11 braced
lists. lists.
@ -2167,18 +2167,18 @@ the configuration (without a prefix: ``Auto``).
f(MyMap[{composite, key}]); f(MyMap[{ composite, key }]); f(MyMap[{composite, key}]); f(MyMap[{ composite, key }]);
new int[3]{1, 2, 3}; new int[3]{ 1, 2, 3 }; new int[3]{1, 2, 3}; new int[3]{ 1, 2, 3 };
**DeriveLineEnding** (``bool``) **DeriveLineEnding** (``Boolean``)
Analyze the formatted file for the most used line ending (``\r\n`` Analyze the formatted file for the most used line ending (``\r\n``
or ``\n``). ``UseCRLF`` is only used as a fallback if none can be derived. or ``\n``). ``UseCRLF`` is only used as a fallback if none can be derived.
**DerivePointerAlignment** (``bool``) **DerivePointerAlignment** (``Boolean``)
If ``true``, analyze the formatted file for the most common If ``true``, analyze the formatted file for the most common
alignment of ``&`` and ``*``. alignment of ``&`` and ``*``.
Pointer and reference alignment styles are going to be updated according Pointer and reference alignment styles are going to be updated according
to the preferences found in the file. to the preferences found in the file.
``PointerAlignment`` is then used only as fallback. ``PointerAlignment`` is then used only as fallback.
**DisableFormat** (``bool``) **DisableFormat** (``Boolean``)
Disables formatting completely. Disables formatting completely.
**EmptyLineAfterAccessModifier** (``EmptyLineAfterAccessModifierStyle``) **EmptyLineAfterAccessModifier** (``EmptyLineAfterAccessModifierStyle``)
@ -2303,7 +2303,7 @@ the configuration (without a prefix: ``Auto``).
**ExperimentalAutoDetectBinPacking** (``bool``) **ExperimentalAutoDetectBinPacking** (``Boolean``)
If ``true``, clang-format detects whether function calls and If ``true``, clang-format detects whether function calls and
definitions are formatted with one parameter per line. definitions are formatted with one parameter per line.
@ -2315,7 +2315,7 @@ the configuration (without a prefix: ``Auto``).
NOTE: This is an experimental flag, that might go away or be renamed. Do 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. not use this in config files, etc. Use at your own risk.
**FixNamespaceComments** (``bool``) **FixNamespaceComments** (``Boolean``)
If ``true``, clang-format adds missing namespace end comments for If ``true``, clang-format adds missing namespace end comments for
short namespaces and fixes invalid existing ones. Short ones are short namespaces and fixes invalid existing ones. Short ones are
controlled by "ShortNamespaceLines". controlled by "ShortNamespaceLines".
@ -2328,7 +2328,7 @@ the configuration (without a prefix: ``Auto``).
bar(); bar(); bar(); bar();
} // namespace a } } // namespace a }
**ForEachMacros** (``std::vector<std::string>``) **ForEachMacros** (``List of Strings``)
A vector of macros that should be interpreted as foreach loops A vector of macros that should be interpreted as foreach loops
instead of as function calls. instead of as function calls.
@ -2347,7 +2347,7 @@ the configuration (without a prefix: ``Auto``).
For example: BOOST_FOREACH. For example: BOOST_FOREACH.
**IfMacros** (``std::vector<std::string>``) **IfMacros** (``List of Strings``)
A vector of macros that should be interpreted as conditionals A vector of macros that should be interpreted as conditionals
instead of as function calls. instead of as function calls.
@ -2409,7 +2409,7 @@ the configuration (without a prefix: ``Auto``).
**IncludeCategories** (``std::vector<IncludeCategory>``) **IncludeCategories** (``List of IncludeCategories``)
Regular expressions denoting the different ``#include`` categories Regular expressions denoting the different ``#include`` categories
used for ordering ``#includes``. used for ordering ``#includes``.
@ -2457,7 +2457,7 @@ the configuration (without a prefix: ``Auto``).
Priority: 1 Priority: 1
SortPriority: 0 SortPriority: 0
**IncludeIsMainRegex** (``std::string``) **IncludeIsMainRegex** (``String``)
Specify a regular expression of suffixes that are allowed in the Specify a regular expression of suffixes that are allowed in the
file-to-main-include mapping. file-to-main-include mapping.
@ -2470,7 +2470,7 @@ the configuration (without a prefix: ``Auto``).
For example, if configured to "(_test)?$", then a header a.h would be seen For example, if configured to "(_test)?$", then a header a.h would be seen
as the "main" include in both a.cc and a_test.cc. as the "main" include in both a.cc and a_test.cc.
**IncludeIsMainSourceRegex** (``std::string``) **IncludeIsMainSourceRegex** (``String``)
Specify a regular expression for files being formatted Specify a regular expression for files being formatted
that are allowed to be considered "main" in the that are allowed to be considered "main" in the
file-to-main-include mapping. file-to-main-include mapping.
@ -2490,7 +2490,7 @@ the configuration (without a prefix: ``Auto``).
``ClassImpl.hpp`` would not have the main include file put on top ``ClassImpl.hpp`` would not have the main include file put on top
before any other include. before any other include.
**IndentAccessModifiers** (``bool``) **IndentAccessModifiers** (``Boolean``)
Specify whether access modifiers should have their own indentation level. Specify whether access modifiers should have their own indentation level.
When ``false``, access modifiers are indented (or outdented) relative to When ``false``, access modifiers are indented (or outdented) relative to
@ -2517,7 +2517,7 @@ the configuration (without a prefix: ``Auto``).
return 1; return 1; return 1; return 1;
} } } }
**IndentCaseBlocks** (``bool``) **IndentCaseBlocks** (``Boolean``)
Indent case label blocks one level from the case label. Indent case label blocks one level from the case label.
When ``false``, the block following the case label uses the same When ``false``, the block following the case label uses the same
@ -2540,7 +2540,7 @@ the configuration (without a prefix: ``Auto``).
} }
} }
**IndentCaseLabels** (``bool``) **IndentCaseLabels** (``Boolean``)
Indent case labels one level from the switch statement. Indent case labels one level from the switch statement.
When ``false``, use the same indentation level as for the switch When ``false``, use the same indentation level as for the switch
@ -2605,7 +2605,7 @@ the configuration (without a prefix: ``Auto``).
**IndentGotoLabels** (``bool``) **IndentGotoLabels** (``Boolean``)
Indent goto labels. Indent goto labels.
When ``false``, goto labels are flushed left. When ``false``, goto labels are flushed left.
@ -2662,7 +2662,7 @@ the configuration (without a prefix: ``Auto``).
**IndentRequires** (``bool``) **IndentRequires** (``Boolean``)
Indent the requires clause in a template Indent the requires clause in a template
.. code-block:: c++ .. code-block:: c++
@ -2681,7 +2681,7 @@ the configuration (without a prefix: ``Auto``).
//.... //....
} }
**IndentWidth** (``unsigned``) **IndentWidth** (``Unsigned``)
The number of columns to use for indentation. The number of columns to use for indentation.
.. code-block:: c++ .. code-block:: c++
@ -2695,7 +2695,7 @@ the configuration (without a prefix: ``Auto``).
} }
} }
**IndentWrappedFunctionNames** (``bool``) **IndentWrappedFunctionNames** (``Boolean``)
Indent if a function definition or declaration is wrapped after the Indent if a function definition or declaration is wrapped after the
type. type.
@ -2741,7 +2741,7 @@ the configuration (without a prefix: ``Auto``).
**JavaImportGroups** (``std::vector<std::string>``) **JavaImportGroups** (``List of Strings``)
A vector of prefixes ordered by the desired groups for Java imports. A vector of prefixes ordered by the desired groups for Java imports.
One group's prefix can be a subset of another - the longest prefix is One group's prefix can be a subset of another - the longest prefix is
@ -2807,7 +2807,7 @@ the configuration (without a prefix: ``Auto``).
**JavaScriptWrapImports** (``bool``) **JavaScriptWrapImports** (``Boolean``)
Whether to wrap JavaScript import/export statements. Whether to wrap JavaScript import/export statements.
.. code-block:: js .. code-block:: js
@ -2822,7 +2822,7 @@ the configuration (without a prefix: ``Auto``).
false: false:
import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js" import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js"
**KeepEmptyLinesAtTheStartOfBlocks** (``bool``) **KeepEmptyLinesAtTheStartOfBlocks** (``Boolean``)
If true, the empty line at the start of blocks is kept. If true, the empty line at the start of blocks is kept.
.. code-block:: c++ .. code-block:: c++
@ -2908,7 +2908,7 @@ the configuration (without a prefix: ``Auto``).
**MacroBlockBegin** (``std::string``) **MacroBlockBegin** (``String``)
A regular expression matching macros that start a block. A regular expression matching macros that start a block.
.. code-block:: c++ .. code-block:: c++
@ -2937,10 +2937,10 @@ the configuration (without a prefix: ``Auto``).
bar(); bar();
NS_TABLE_FOO_END NS_TABLE_FOO_END
**MacroBlockEnd** (``std::string``) **MacroBlockEnd** (``String``)
A regular expression matching macros that end a block. A regular expression matching macros that end a block.
**MaxEmptyLinesToKeep** (``unsigned``) **MaxEmptyLinesToKeep** (``Unsigned``)
The maximum number of consecutive empty lines to keep. The maximum number of consecutive empty lines to keep.
.. code-block:: c++ .. code-block:: c++
@ -2997,7 +2997,7 @@ the configuration (without a prefix: ``Auto``).
**NamespaceMacros** (``std::vector<std::string>``) **NamespaceMacros** (``List of Strings``)
A vector of macros which are used to open namespace blocks. A vector of macros which are used to open namespace blocks.
These are expected to be macros of the form: These are expected to be macros of the form:
@ -3056,7 +3056,7 @@ the configuration (without a prefix: ``Auto``).
**ObjCBlockIndentWidth** (``unsigned``) **ObjCBlockIndentWidth** (``Unsigned``)
The number of characters to use for indentation of ObjC blocks. The number of characters to use for indentation of ObjC blocks.
.. code-block:: objc .. code-block:: objc
@ -3067,7 +3067,7 @@ the configuration (without a prefix: ``Auto``).
[self onOperationDone]; [self onOperationDone];
}]; }];
**ObjCBreakBeforeNestedBlockParam** (``bool``) **ObjCBreakBeforeNestedBlockParam** (``Boolean``)
Break parameters list into lines when there is nested block Break parameters list into lines when there is nested block
parameters in a function call. parameters in a function call.
@ -3091,15 +3091,15 @@ the configuration (without a prefix: ``Auto``).
}] }]
} }
**ObjCSpaceAfterProperty** (``bool``) **ObjCSpaceAfterProperty** (``Boolean``)
Add a space after ``@property`` in Objective-C, i.e. use Add a space after ``@property`` in Objective-C, i.e. use
``@property (readonly)`` instead of ``@property(readonly)``. ``@property (readonly)`` instead of ``@property(readonly)``.
**ObjCSpaceBeforeProtocolList** (``bool``) **ObjCSpaceBeforeProtocolList** (``Boolean``)
Add a space in front of an Objective-C protocol list, i.e. use Add a space in front of an Objective-C protocol list, i.e. use
``Foo <Protocol>`` instead of ``Foo<Protocol>``. ``Foo <Protocol>`` instead of ``Foo<Protocol>``.
**PPIndentWidth** (``int``) **PPIndentWidth** (``Integer``)
The number of columns to use for indentation of preprocessor statements. The number of columns to use for indentation of preprocessor statements.
When set to -1 (default) ``IndentWidth`` is used also for preprocessor When set to -1 (default) ``IndentWidth`` is used also for preprocessor
statements. statements.
@ -3168,32 +3168,32 @@ the configuration (without a prefix: ``Auto``).
**PenaltyBreakAssignment** (``unsigned``) **PenaltyBreakAssignment** (``Unsigned``)
The penalty for breaking around an assignment operator. The penalty for breaking around an assignment operator.
**PenaltyBreakBeforeFirstCallParameter** (``unsigned``) **PenaltyBreakBeforeFirstCallParameter** (``Unsigned``)
The penalty for breaking a function call after ``call(``. The penalty for breaking a function call after ``call(``.
**PenaltyBreakComment** (``unsigned``) **PenaltyBreakComment** (``Unsigned``)
The penalty for each line break introduced inside a comment. The penalty for each line break introduced inside a comment.
**PenaltyBreakFirstLessLess** (``unsigned``) **PenaltyBreakFirstLessLess** (``Unsigned``)
The penalty for breaking before the first ``<<``. The penalty for breaking before the first ``<<``.
**PenaltyBreakString** (``unsigned``) **PenaltyBreakString** (``Unsigned``)
The penalty for each line break introduced inside a string literal. The penalty for each line break introduced inside a string literal.
**PenaltyBreakTemplateDeclaration** (``unsigned``) **PenaltyBreakTemplateDeclaration** (``Unsigned``)
The penalty for breaking after template declaration. The penalty for breaking after template declaration.
**PenaltyExcessCharacter** (``unsigned``) **PenaltyExcessCharacter** (``Unsigned``)
The penalty for each character outside of the column limit. The penalty for each character outside of the column limit.
**PenaltyIndentedWhitespace** (``unsigned``) **PenaltyIndentedWhitespace** (``Unsigned``)
Penalty for each character of whitespace indentation Penalty for each character of whitespace indentation
(counted relative to leading non-whitespace column). (counted relative to leading non-whitespace column).
**PenaltyReturnTypeOnItsOwnLine** (``unsigned``) **PenaltyReturnTypeOnItsOwnLine** (``Unsigned``)
Penalty for putting the return type of a function onto its own Penalty for putting the return type of a function onto its own
line. line.
@ -3276,7 +3276,7 @@ the configuration (without a prefix: ``Auto``).
**QualifierOrder** (``std::vector<std::string>``) **QualifierOrder** (``List of Strings``)
The Order in which the qualifiers appear. The Order in which the qualifiers appear.
Order is a an array can contain any of the following Order is a an array can contain any of the following
@ -3297,7 +3297,7 @@ the configuration (without a prefix: ``Auto``).
QualifierOrder: ['inline', 'static', 'type', 'const', 'volatile' ] QualifierOrder: ['inline', 'static', 'type', 'const', 'volatile' ]
**RawStringFormats** (``std::vector<RawStringFormat>``) **RawStringFormats** (``List of RawStringFormats``)
Defines hints for detecting supported languages code blocks in raw Defines hints for detecting supported languages code blocks in raw
strings. strings.
@ -3367,7 +3367,7 @@ the configuration (without a prefix: ``Auto``).
**ReflowComments** (``bool``) **ReflowComments** (``Boolean``)
If ``true``, clang-format will attempt to re-flow comments. If ``true``, clang-format will attempt to re-flow comments.
.. code-block:: c++ .. code-block:: c++
@ -3382,7 +3382,7 @@ the configuration (without a prefix: ``Auto``).
/* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
* information */ * information */
**ShortNamespaceLines** (``unsigned``) **ShortNamespaceLines** (``Unsigned``)
The maximal number of unwrapped lines that a short namespace spans. The maximal number of unwrapped lines that a short namespace spans.
Defaults to 1. Defaults to 1.
@ -3476,7 +3476,7 @@ the configuration (without a prefix: ``Auto``).
**SortUsingDeclarations** (``bool``) **SortUsingDeclarations** (``Boolean``)
If ``true``, clang-format will sort using declarations. If ``true``, clang-format will sort using declarations.
The order of using declarations is defined as follows: The order of using declarations is defined as follows:
@ -3493,7 +3493,7 @@ the configuration (without a prefix: ``Auto``).
using std::cout; vs. using std::cin; using std::cout; vs. using std::cin;
using std::cin; using std::cout; using std::cin; using std::cout;
**SpaceAfterCStyleCast** (``bool``) **SpaceAfterCStyleCast** (``Boolean``)
If ``true``, a space is inserted after C style casts. If ``true``, a space is inserted after C style casts.
.. code-block:: c++ .. code-block:: c++
@ -3501,7 +3501,7 @@ the configuration (without a prefix: ``Auto``).
true: false: true: false:
(int) i; vs. (int)i; (int) i; vs. (int)i;
**SpaceAfterLogicalNot** (``bool``) **SpaceAfterLogicalNot** (``Boolean``)
If ``true``, a space is inserted after the logical not operator (``!``). If ``true``, a space is inserted after the logical not operator (``!``).
.. code-block:: c++ .. code-block:: c++
@ -3509,7 +3509,7 @@ the configuration (without a prefix: ``Auto``).
true: false: true: false:
! someExpression(); vs. !someExpression(); ! someExpression(); vs. !someExpression();
**SpaceAfterTemplateKeyword** (``bool``) **SpaceAfterTemplateKeyword** (``Boolean``)
If ``true``, a space will be inserted after the 'template' keyword. If ``true``, a space will be inserted after the 'template' keyword.
.. code-block:: c++ .. code-block:: c++
@ -3557,7 +3557,7 @@ the configuration (without a prefix: ``Auto``).
**SpaceBeforeAssignmentOperators** (``bool``) **SpaceBeforeAssignmentOperators** (``Boolean``)
If ``false``, spaces will be removed before assignment operators. If ``false``, spaces will be removed before assignment operators.
.. code-block:: c++ .. code-block:: c++
@ -3566,7 +3566,7 @@ the configuration (without a prefix: ``Auto``).
int a = 5; vs. int a= 5; int a = 5; vs. int a= 5;
a += 42; a+= 42; a += 42; a+= 42;
**SpaceBeforeCaseColon** (``bool``) **SpaceBeforeCaseColon** (``Boolean``)
If ``false``, spaces will be removed before case colon. If ``false``, spaces will be removed before case colon.
.. code-block:: c++ .. code-block:: c++
@ -3576,7 +3576,7 @@ the configuration (without a prefix: ``Auto``).
case 1 : break; case 1: break; case 1 : break; case 1: break;
} } } }
**SpaceBeforeCpp11BracedList** (``bool``) **SpaceBeforeCpp11BracedList** (``Boolean``)
If ``true``, a space will be inserted before a C++11 braced list If ``true``, a space will be inserted before a C++11 braced list
used to initialize an object (after the preceding identifier or type). used to initialize an object (after the preceding identifier or type).
@ -3588,7 +3588,7 @@ the configuration (without a prefix: ``Auto``).
vector<int> { 1, 2, 3 }; vector<int>{ 1, 2, 3 }; vector<int> { 1, 2, 3 }; vector<int>{ 1, 2, 3 };
new int[3] { 1, 2, 3 }; new int[3]{ 1, 2, 3 }; new int[3] { 1, 2, 3 }; new int[3]{ 1, 2, 3 };
**SpaceBeforeCtorInitializerColon** (``bool``) **SpaceBeforeCtorInitializerColon** (``Boolean``)
If ``false``, spaces will be removed before constructor initializer If ``false``, spaces will be removed before constructor initializer
colon. colon.
@ -3597,7 +3597,7 @@ the configuration (without a prefix: ``Auto``).
true: false: true: false:
Foo::Foo() : a(a) {} Foo::Foo(): a(a) {} Foo::Foo() : a(a) {} Foo::Foo(): a(a) {}
**SpaceBeforeInheritanceColon** (``bool``) **SpaceBeforeInheritanceColon** (``Boolean``)
If ``false``, spaces will be removed before inheritance colon. If ``false``, spaces will be removed before inheritance colon.
.. code-block:: c++ .. code-block:: c++
@ -3677,7 +3677,7 @@ the configuration (without a prefix: ``Auto``).
**SpaceBeforeRangeBasedForLoopColon** (``bool``) **SpaceBeforeRangeBasedForLoopColon** (``Boolean``)
If ``false``, spaces will be removed before range-based for loop If ``false``, spaces will be removed before range-based for loop
colon. colon.
@ -3686,7 +3686,7 @@ the configuration (without a prefix: ``Auto``).
true: false: true: false:
for (auto v : values) {} vs. for(auto v: values) {} for (auto v : values) {} vs. for(auto v: values) {}
**SpaceBeforeSquareBrackets** (``bool``) **SpaceBeforeSquareBrackets** (``Boolean``)
If ``true``, spaces will be before ``[``. If ``true``, spaces will be before ``[``.
Lambdas will not be affected. Only the first ``[`` will get a space added. Lambdas will not be affected. Only the first ``[`` will get a space added.
@ -3696,7 +3696,7 @@ the configuration (without a prefix: ``Auto``).
int a [5]; vs. int a[5]; int a [5]; vs. int a[5];
int a [5][5]; vs. int a[5][5]; int a [5][5]; vs. int a[5][5];
**SpaceInEmptyBlock** (``bool``) **SpaceInEmptyBlock** (``Boolean``)
If ``true``, spaces will be inserted into ``{}``. If ``true``, spaces will be inserted into ``{}``.
.. code-block:: c++ .. code-block:: c++
@ -3705,7 +3705,7 @@ the configuration (without a prefix: ``Auto``).
void f() { } vs. void f() {} void f() { } vs. void f() {}
while (true) { } while (true) {} while (true) { } while (true) {}
**SpaceInEmptyParentheses** (``bool``) **SpaceInEmptyParentheses** (``Boolean``)
If ``true``, spaces may be inserted into ``()``. If ``true``, spaces may be inserted into ``()``.
.. code-block:: c++ .. code-block:: c++
@ -3718,7 +3718,7 @@ the configuration (without a prefix: ``Auto``).
} } } }
} } } }
**SpacesBeforeTrailingComments** (``unsigned``) **SpacesBeforeTrailingComments** (``Unsigned``)
The number of spaces before trailing line comments The number of spaces before trailing line comments
(``//`` - comments). (``//`` - comments).
@ -3762,7 +3762,7 @@ the configuration (without a prefix: ``Auto``).
**SpacesInCStyleCastParentheses** (``bool``) **SpacesInCStyleCastParentheses** (``Boolean``)
If ``true``, spaces may be inserted into C style casts. If ``true``, spaces may be inserted into C style casts.
.. code-block:: c++ .. code-block:: c++
@ -3770,7 +3770,7 @@ the configuration (without a prefix: ``Auto``).
true: false: true: false:
x = ( int32 )y vs. x = (int32)y x = ( int32 )y vs. x = (int32)y
**SpacesInConditionalStatement** (``bool``) **SpacesInConditionalStatement** (``Boolean``)
If ``true``, spaces will be inserted around if/for/switch/while If ``true``, spaces will be inserted around if/for/switch/while
conditions. conditions.
@ -3780,7 +3780,7 @@ the configuration (without a prefix: ``Auto``).
if ( a ) { ... } vs. if (a) { ... } if ( a ) { ... } vs. if (a) { ... }
while ( i < 5 ) { ... } while (i < 5) { ... } while ( i < 5 ) { ... } while (i < 5) { ... }
**SpacesInContainerLiterals** (``bool``) **SpacesInContainerLiterals** (``Boolean``)
If ``true``, spaces are inserted inside container literals (e.g. If ``true``, spaces are inserted inside container literals (e.g.
ObjC and Javascript array and dict literals). ObjC and Javascript array and dict literals).
@ -3827,7 +3827,7 @@ the configuration (without a prefix: ``Auto``).
* ``unsigned Maximum`` The maximum number of spaces at the start of the comment. * ``unsigned Maximum`` The maximum number of spaces at the start of the comment.
**SpacesInParentheses** (``bool``) **SpacesInParentheses** (``Boolean``)
If ``true``, spaces will be inserted after ``(`` and before ``)``. If ``true``, spaces will be inserted after ``(`` and before ``)``.
.. code-block:: c++ .. code-block:: c++
@ -3835,7 +3835,7 @@ the configuration (without a prefix: ``Auto``).
true: false: true: false:
t f( Deleted & ) & = delete; vs. t f(Deleted &) & = delete; t f( Deleted & ) & = delete; vs. t f(Deleted &) & = delete;
**SpacesInSquareBrackets** (``bool``) **SpacesInSquareBrackets** (``Boolean``)
If ``true``, spaces will be inserted after ``[`` and before ``]``. If ``true``, spaces will be inserted after ``[`` and before ``]``.
Lambdas without arguments or unspecified size array declarations will not Lambdas without arguments or unspecified size array declarations will not
be affected. be affected.
@ -3881,7 +3881,7 @@ the configuration (without a prefix: ``Auto``).
**StatementAttributeLikeMacros** (``std::vector<std::string>``) **StatementAttributeLikeMacros** (``List of Strings``)
Macros which are ignored in front of a statement, as if they were an Macros which are ignored in front of a statement, as if they were an
attribute. So that they are not parsed as identifier, for example for Qts attribute. So that they are not parsed as identifier, for example for Qts
emit. emit.
@ -3898,7 +3898,7 @@ the configuration (without a prefix: ``Auto``).
unsigned char data = 'x'; unsigned char data = 'x';
emit signal(data); // Now it's fine again. emit signal(data); // Now it's fine again.
**StatementMacros** (``std::vector<std::string>``) **StatementMacros** (``List of Strings``)
A vector of macros that should be interpreted as complete A vector of macros that should be interpreted as complete
statements. statements.
@ -3908,10 +3908,10 @@ the configuration (without a prefix: ``Auto``).
For example: Q_UNUSED For example: Q_UNUSED
**TabWidth** (``unsigned``) **TabWidth** (``Unsigned``)
The number of columns used for tab stops. The number of columns used for tab stops.
**TypenameMacros** (``std::vector<std::string>``) **TypenameMacros** (``List of Strings``)
A vector of macros that should be interpreted as type declarations A vector of macros that should be interpreted as type declarations
instead of as function calls. instead of as function calls.
@ -3929,7 +3929,7 @@ the configuration (without a prefix: ``Auto``).
For example: OpenSSL STACK_OF, BSD LIST_ENTRY. For example: OpenSSL STACK_OF, BSD LIST_ENTRY.
**UseCRLF** (``bool``) **UseCRLF** (``Boolean``)
Use ``\r\n`` instead of ``\n`` for line breaks. Use ``\r\n`` instead of ``\n`` for line breaks.
Also used as fallback if ``DeriveLineEnding`` is true. Also used as fallback if ``DeriveLineEnding`` is true.
@ -3958,7 +3958,7 @@ the configuration (without a prefix: ``Auto``).
**WhitespaceSensitiveMacros** (``std::vector<std::string>``) **WhitespaceSensitiveMacros** (``List of Strings``)
A vector of macros which are whitespace-sensitive and should not A vector of macros which are whitespace-sensitive and should not
be touched. be touched.

69
clang/docs/tools/dump_format_style.py
View File

@ -1,23 +1,78 @@
#!/usr/bin/env python #!/usr/bin/env python3
# A tool to parse the FormatStyle struct from Format.h and update the # A tool to parse the FormatStyle struct from Format.h and update the
# documentation in ../ClangFormatStyleOptions.rst automatically. # documentation in ../ClangFormatStyleOptions.rst automatically.
# Run from the directory in which this file is located to update the docs. # Run from the directory in which this file is located to update the docs.
import collections import inspect
import os import os
import re import re
from typing import Set
CLANG_DIR = os.path.join(os.path.dirname(__file__), '../..') CLANG_DIR = os.path.join(os.path.dirname(__file__), '../..')
FORMAT_STYLE_FILE = os.path.join(CLANG_DIR, 'include/clang/Format/Format.h') FORMAT_STYLE_FILE = os.path.join(CLANG_DIR, 'include/clang/Format/Format.h')
INCLUDE_STYLE_FILE = os.path.join(CLANG_DIR, 'include/clang/Tooling/Inclusions/IncludeStyle.h') INCLUDE_STYLE_FILE = os.path.join(CLANG_DIR, 'include/clang/Tooling/Inclusions/IncludeStyle.h')
DOC_FILE = os.path.join(CLANG_DIR, 'docs/ClangFormatStyleOptions.rst') DOC_FILE = os.path.join(CLANG_DIR, 'docs/ClangFormatStyleOptions.rst')
PLURALS_FILE = os.path.join(os.path.dirname(__file__), 'plurals.txt')
plurals: Set[str] = set()
with open(PLURALS_FILE, 'a+') as f:
f.seek(0)
plurals = set(f.read().splitlines())
def substitute(text, tag, contents): def substitute(text, tag, contents):
replacement = '\n.. START_%s\n\n%s\n\n.. END_%s\n' % (tag, contents, tag) replacement = '\n.. START_%s\n\n%s\n\n.. END_%s\n' % (tag, contents, tag)
pattern = r'\n\.\. START_%s\n.*\n\.\. END_%s\n' % (tag, tag) pattern = r'\n\.\. START_%s\n.*\n\.\. END_%s\n' % (tag, tag)
return re.sub(pattern, '%s', text, flags=re.S) % replacement return re.sub(pattern, '%s', text, flags=re.S) % replacement
def register_plural(singular: str, plural: str):
if plural not in plurals:
if not hasattr(register_plural, "generated_new_plural"):
print('Plural generation: you can use '
f'`git checkout -- {os.path.relpath(PLURALS_FILE)}` '
'to reemit warnings or `git add` to include new plurals\n')
register_plural.generated_new_plural = True
plurals.add(plural)
with open(PLURALS_FILE, 'a') as f:
f.write(plural + '\n')
cf = inspect.currentframe()
lineno = ''
if cf and cf.f_back:
lineno = ':' + str(cf.f_back.f_lineno)
print(f'{__file__}{lineno} check if plural of {singular} is {plural}', file=os.sys.stderr)
return plural
def pluralize(word: str):
lword = word.lower()
if len(lword) >= 2 and lword[-1] == 'y' and lword[-2] not in 'aeiou':
return register_plural(word, word[:-1] + 'ies')
elif lword.endswith(('s', 'sh', 'ch', 'x', 'z')):
return register_plural(word, word[:-1] + 'es')
elif lword.endswith('fe'):
return register_plural(word, word[:-2] + 'ves')
elif lword.endswith('f') and not lword.endswith('ff'):
return register_plural(word, word[:-1] + 'ves')
else:
return register_plural(word, word + 's')
def to_yaml_type(typestr: str):
if typestr == 'bool':
return 'Boolean'
elif typestr == 'int':
return 'Integer'
elif typestr == 'unsigned':
return 'Unsigned'
elif typestr == 'std::string':
return 'String'
subtype, napplied = re.subn(r'^std::vector<(.*)>$', r'\1', typestr)
if napplied == 1:
return 'List of ' + pluralize(to_yaml_type(subtype))
return typestr
def doxygen2rst(text): def doxygen2rst(text):
text = re.sub(r'<tt>\s*(.*?)\s*<\/tt>', r'``\1``', text) text = re.sub(r'<tt>\s*(.*?)\s*<\/tt>', r'``\1``', text)
text = re.sub(r'\\c ([^ ,;\.]+)', r'``\1``', text) text = re.sub(r'\\c ([^ ,;\.]+)', r'``\1``', text)
@ -40,7 +95,7 @@ class Option(object):
self.nested_struct = None self.nested_struct = None
def __str__(self): def __str__(self):
s = '**%s** (``%s``)\n%s' % (self.name, self.type, s = '**%s** (``%s``)\n%s' % (self.name, to_yaml_type(self.type),
doxygen2rst(indent(self.comment, 2))) doxygen2rst(indent(self.comment, 2)))
if self.enum and self.enum.values: if self.enum and self.enum.values:
s += indent('\n\nPossible values:\n\n%s\n' % self.enum, 2) s += indent('\n\nPossible values:\n\n%s\n' % self.enum, 2)
@ -85,7 +140,7 @@ class NestedEnum(object):
self.type = enumtype self.type = enumtype
def __str__(self): def __str__(self):
s = '\n* ``%s %s``\n%s' % (self.type, self.name, s = '\n* ``%s %s``\n%s' % (to_yaml_type(self.type), self.name,
doxygen2rst(indent(self.comment, 2))) doxygen2rst(indent(self.comment, 2)))
s += indent('\nPossible values:\n\n', 2) s += indent('\nPossible values:\n\n', 2)
s += indent('\n'.join(map(str, self.values)),2) s += indent('\n'.join(map(str, self.values)),2)
@ -129,7 +184,7 @@ def clean_comment_line(line):
def read_options(header): def read_options(header):
class State(object): class State(object):
BeforeStruct, Finished, InStruct, InNestedStruct, InNestedFieldComent, \ BeforeStruct, Finished, InStruct, InNestedStruct, InNestedFieldComment, \
InFieldComment, InEnum, InEnumMemberComment = range(8) InFieldComment, InEnum, InEnumMemberComment = range(8)
state = State.BeforeStruct state = State.BeforeStruct
@ -173,12 +228,12 @@ def read_options(header):
raise Exception('Invalid format, expected comment, field or enum') raise Exception('Invalid format, expected comment, field or enum')
elif state == State.InNestedStruct: elif state == State.InNestedStruct:
if line.startswith('///'): if line.startswith('///'):
state = State.InNestedFieldComent state = State.InNestedFieldComment
comment = clean_comment_line(line) comment = clean_comment_line(line)
elif line == '};': elif line == '};':
state = State.InStruct state = State.InStruct
nested_structs[nested_struct.name] = nested_struct nested_structs[nested_struct.name] = nested_struct
elif state == State.InNestedFieldComent: elif state == State.InNestedFieldComment:
if line.startswith('///'): if line.startswith('///'):
comment += clean_comment_line(line) comment += clean_comment_line(line)
else: else:

3
clang/docs/tools/plurals.txt Normal file
View File

@ -0,0 +1,3 @@
Strings
IncludeCategories
RawStringFormats