intel/llvm
1
0
Fork 0
mirror of https://github.com/intel/llvm.git synced 2026-02-05 13:21:04 +08:00
Code Issues Packages Projects Releases Wiki Activity

Clean up clang-format options documentation. NFC

Browse Source 
Use uniform style for inline code blocks, specify language for YAML code blocks,
various formatting fixes etc.

llvm-svn: 261645
This commit is contained in:
Alexander Kornienko
2016-02-23 16:12:00 +00:00
parent 32718b6a0c
commit b00a7d2fec
2 changed files with 186 additions and 135 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
clang/docs/ClangFormatStyleOptions.rst
View File

@@ -148,7 +148,7 @@ the configuration (without a prefix: ``Auto``).
.. START_FORMAT_STYLE_OPTIONS
**AccessModifierOffset** (``int``)
The extra indent or outdent of access modifiers, e.g. ``public:``.
The extra indent or outdent of access modifiers, e.g. ``public``:.
**AlignAfterOpenBracket** (``BracketAlignmentStyle``)
If ``true``, horizontally aligns arguments after an open bracket.
@@ -165,6 +165,7 @@ the configuration (without a prefix: ``Auto``).
someLongFunction(argument1,
argument2);
* ``BAS_DontAlign`` (in configuration: ``DontAlign``)
Don't align, instead use ``ContinuationIndentWidth``, e.g.:
@@ -172,6 +173,7 @@ the configuration (without a prefix: ``Auto``).
someLongFunction(argument1,
argument2);
* ``BAS_AlwaysBreak`` (in configuration: ``AlwaysBreak``)
Always break after an open bracket, if the parameters don't fit
on a single line, e.g.:
@@ -182,6 +184,7 @@ the configuration (without a prefix: ``Auto``).
argument1, argument2);
**AlignConsecutiveAssignments** (``bool``)
If ``true``, aligns consecutive assignments.
@@ -238,28 +241,31 @@ the configuration (without a prefix: ``Auto``).
If ``true``, short case labels will be contracted to a single line.
**AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``)
Dependent on the value, ``int f() { return 0; }`` can be put
on a single line.
Dependent on the value, ``int f() { return 0; }`` can be put on a
single line.
Possible values:
* ``SFS_None`` (in configuration: ``None``)
Never merge functions into a single line.
* ``SFS_Empty`` (in configuration: ``Empty``)
Only merge empty functions.
* ``SFS_Inline`` (in configuration: ``Inline``)
Only merge functions defined inside a class. Implies "empty".
* ``SFS_All`` (in configuration: ``All``)
Merge all functions fitting on a single line.
**AllowShortIfStatementsOnASingleLine** (``bool``)
If ``true``, ``if (a) return;`` can be put on a single
line.
If ``true``, ``if (a) return;`` can be put on a single line.
**AllowShortLoopsOnASingleLine** (``bool``)
If ``true``, ``while (true) continue;`` can be put on a
single line.
If ``true``, ``while (true) continue;`` can be put on a single
line.
**AlwaysBreakAfterDefinitionReturnType** (``DefinitionReturnTypeBreakingStyle``)
The function definition return type breaking style to use. This
@@ -270,12 +276,15 @@ the configuration (without a prefix: ``Auto``).
* ``DRTBS_None`` (in configuration: ``None``)
Break after return type automatically.
``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
* ``DRTBS_All`` (in configuration: ``All``)
Always break after the return type.
* ``DRTBS_TopLevel`` (in configuration: ``TopLevel``)
Always break after the return types of top-level functions.
**AlwaysBreakAfterReturnType** (``ReturnTypeBreakingStyle``)
The function declaration return type breaking style to use.
@@ -284,16 +293,21 @@ the configuration (without a prefix: ``Auto``).
* ``RTBS_None`` (in configuration: ``None``)
Break after return type automatically.
``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
* ``RTBS_All`` (in configuration: ``All``)
Always break after the return type.
* ``RTBS_TopLevel`` (in configuration: ``TopLevel``)
Always break after the return types of top-level functions.
* ``RTBS_AllDefinitions`` (in configuration: ``AllDefinitions``)
Always break after the return type of function definitions.
* ``RTBS_TopLevelDefinitions`` (in configuration: ``TopLevelDefinitions``)
Always break after the return type of top-level definitions.
**AlwaysBreakBeforeMultilineStrings** (``bool``)
If ``true``, always break before multiline string literals.
@@ -303,8 +317,8 @@ the configuration (without a prefix: ``Auto``).
``ContinuationIndentWidth`` spaces from the start of the line.
**AlwaysBreakTemplateDeclarations** (``bool``)
If ``true``, always break after the ``template<...>`` of a
template declaration.
If ``true``, always break after the ``template<...>`` of a template
declaration.
**BinPackArguments** (``bool``)
If ``false``, a function call's arguments will either be all on the
@@ -317,17 +331,17 @@ the configuration (without a prefix: ``Auto``).
**BraceWrapping** (``BraceWrappingFlags``)
Control of individual brace wrapping cases.
If ``BreakBeforeBraces`` is set to ``custom``, use this to specify how each
individual brace case should be handled. Otherwise, this is ignored.
If ``BreakBeforeBraces`` is set to ``BS_Custom``, use this to specify how
each individual brace case should be handled. Otherwise, this is ignored.
Nested configuration flags:
* ``bool AfterClass`` Wrap class definitions.
* ``bool AfterControlStatement`` Wrap control statements (if/for/while/switch/..).
* ``bool AfterControlStatement`` Wrap control statements (``if``/``for``/``while``/``switch``/..).
* ``bool AfterEnum`` Wrap enum definitions.
* ``bool AfterFunction`` Wrap function definitions.
* ``bool AfterNamespace`` Wrap namespace definitions.
* ``bool AfterObjCDeclaration`` Wrap ObjC definitions (@autoreleasepool, interfaces, ..).
* ``bool AfterObjCDeclaration`` Wrap ObjC definitions (``@autoreleasepool``, interfaces, ..).
* ``bool AfterStruct`` Wrap struct definitions.
* ``bool AfterUnion`` Wrap union definitions.
* ``bool BeforeCatch`` Wrap before ``catch``.
@@ -345,12 +359,15 @@ the configuration (without a prefix: ``Auto``).
* ``BOS_None`` (in configuration: ``None``)
Break after operators.
* ``BOS_NonAssignment`` (in configuration: ``NonAssignment``)
Break before operators that aren't assignments.
* ``BOS_All`` (in configuration: ``All``)
Break before operators.
**BreakBeforeBraces** (``BraceBreakingStyle``)
The brace breaking style to use.
@@ -358,24 +375,33 @@ the configuration (without a prefix: ``Auto``).
* ``BS_Attach`` (in configuration: ``Attach``)
Always attach braces to surrounding context.
* ``BS_Linux`` (in configuration: ``Linux``)
Like ``Attach``, but break before braces on function, namespace and
class definitions.
* ``BS_Mozilla`` (in configuration: ``Mozilla``)
Like ``Attach``, but break before braces on enum, function, and record
definitions.
* ``BS_Stroustrup`` (in configuration: ``Stroustrup``)
Like ``Attach``, but break before function definitions, 'catch', and 'else'.
Like ``Attach``, but break before function definitions, ``catch``, and
``else``.
* ``BS_Allman`` (in configuration: ``Allman``)
Always break before braces.
* ``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.
* ``BS_WebKit`` (in configuration: ``WebKit``)
Like ``Attach``, but break before functions.
* ``BS_Custom`` (in configuration: ``Custom``)
Configure each individual brace in ``BraceWrapping``.
Configure each individual brace in `BraceWrapping`.
**BreakBeforeTernaryOperators** (``bool``)
@@ -427,7 +453,8 @@ the configuration (without a prefix: ``Auto``).
**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 ``\*``. ``PointerAlignment`` is then used only as
fallback.
**DisableFormat** (``bool``)
Disables formatting completely.
@@ -457,32 +484,32 @@ the configuration (without a prefix: ``Auto``).
In the .clang-format configuration file, this can be configured like:
.. code-block:: c++
.. code-block:: yaml
ForEachMacros: ['RANGES_FOR', 'FOREACH']
For example: BOOST_FOREACH.
**IncludeCategories** (``std::vector<IncludeCategory>``)
Regular expressions denoting the different #include categories used
for ordering #includes.
Regular expressions denoting the different ``#include`` categories
used for ordering ``#includes``.
These regular expressions are matched against the filename of an include
(including the <> or "") in order. The value belonging to the first
matching regular expression is assigned and #includes are sorted first
matching regular expression is assigned and ``#includes`` are sorted first
according to increasing category number and then alphabetically within
each category.
If none of the regular expressions match, INT_MAX is assigned as
category. The main header for a source file automatically gets category 0.
so that it is generally kept at the beginning of the #includes
so that it is generally kept at the beginning of the ``#includes``
(http://llvm.org/docs/CodingStandards.html#include-style). However, you
can also assign negative priorities if you have certain headers that
always need to be first.
To configure this in the .clang-format file, use:
.. code-block:: c++
.. code-block:: yaml
IncludeCategories:
- Regex: '^"(llvm|llvm-c|clang|clang-c)/'
@@ -515,19 +542,25 @@ the configuration (without a prefix: ``Auto``).
* ``LK_None`` (in configuration: ``None``)
Do not use.
* ``LK_Cpp`` (in configuration: ``Cpp``)
Should be used for C, C++, ObjectiveC, ObjectiveC++.
* ``LK_Java`` (in configuration: ``Java``)
Should be used for Java.
* ``LK_JavaScript`` (in configuration: ``JavaScript``)
Should be used for JavaScript.
* ``LK_Proto`` (in configuration: ``Proto``)
Should be used for Protocol Buffers
(https://developers.google.com/protocol-buffers/).
* ``LK_TableGen`` (in configuration: ``TableGen``)
Should be used for TableGen code.
**MacroBlockBegin** (``std::string``)
A regular expression matching macros that start a block.
@@ -544,25 +577,28 @@ the configuration (without a prefix: ``Auto``).
* ``NI_None`` (in configuration: ``None``)
Don't indent in namespaces.
* ``NI_Inner`` (in configuration: ``Inner``)
Indent only in inner namespaces (nested in other namespaces).
* ``NI_All`` (in configuration: ``All``)
Indent in all namespaces.
**ObjCBlockIndentWidth** (``unsigned``)
The number of characters to use for indentation of ObjC blocks.
**ObjCSpaceAfterProperty** (``bool``)
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``)
Add a space in front of an Objective-C protocol list, i.e. use
``Foo <Protocol>`` instead of ``Foo<Protocol>``.
**PenaltyBreakBeforeFirstCallParameter** (``unsigned``)
The penalty for breaking a function call after "call(".
The penalty for breaking a function call after ``call(``.
**PenaltyBreakComment** (``unsigned``)
The penalty for each line break introduced inside a comment.
@@ -587,17 +623,20 @@ the configuration (without a prefix: ``Auto``).
* ``PAS_Left`` (in configuration: ``Left``)
Align pointer to the left.
* ``PAS_Right`` (in configuration: ``Right``)
Align pointer to the right.
* ``PAS_Middle`` (in configuration: ``Middle``)
Align pointer in the middle.
**ReflowComments** (``bool``)
If true, clang-format will attempt to re-flow comments.
If ``true``, clang-format will attempt to re-flow comments.
**SortIncludes** (``bool``)
If true, clang-format will sort #includes.
If ``true``, clang-format will sort ``#includes``.
**SpaceAfterCStyleCast** (``bool``)
If ``true``, a space may be inserted after C style casts.
@@ -612,9 +651,11 @@ the configuration (without a prefix: ``Auto``).
* ``SBPO_Never`` (in configuration: ``Never``)
Never put a space before opening parentheses.
* ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``)
Put a space before opening parentheses only after control statement
keywords (``for/if/while...``).
* ``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
@@ -622,19 +663,21 @@ the configuration (without a prefix: ``Auto``).
parentheses, etc.)
**SpaceInEmptyParentheses** (``bool``)
If ``true``, spaces may be inserted into '()'.
If ``true``, spaces may be inserted into ``()``.
**SpacesBeforeTrailingComments** (``unsigned``)
The number of spaces before trailing line comments
(``//`` - comments).
This does not affect trailing block comments (``/**/`` - comments) as those
commonly have different usage patterns and a number of special cases.
This does not affect trailing block comments (``/**/`` - comments) as
those commonly have different usage patterns and a number of special
cases.
**SpacesInAngles** (``bool``)
If ``true``, spaces will be inserted after '<' and before '>' in
template argument lists
If ``true``, spaces will be inserted after ``<`` and before ``>``
in template argument lists.
**SpacesInCStyleCastParentheses** (``bool``)
If ``true``, spaces may be inserted into C style casts.
@@ -644,26 +687,28 @@ the configuration (without a prefix: ``Auto``).
ObjC and Javascript array and dict literals).
**SpacesInParentheses** (``bool``)
If ``true``, spaces will be inserted after '(' and before ')'.
If ``true``, spaces will be inserted after ``(`` and before ``)``.
**SpacesInSquareBrackets** (``bool``)
If ``true``, spaces will be inserted after '[' and before ']'.
If ``true``, spaces will be inserted after ``[`` and before ``]``.
**Standard** (``LanguageStandard``)
Format compatible with this standard, e.g. use
``A<A<int> >`` instead of ``A<A<int>>`` for LS_Cpp03.
Format compatible with this standard, e.g. use ``A<A<int> >``
instead of ``A<A<int>>`` for ``LS_Cpp03``.
Possible values:
* ``LS_Cpp03`` (in configuration: ``Cpp03``)
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 (e.g. ``A<A<int>>`` instead of ``A<A<int> >``).
* ``LS_Auto`` (in configuration: ``Auto``)
Automatic detection based on the input.
**TabWidth** (``unsigned``)
The number of columns used for tab stops.
@@ -674,13 +719,16 @@ the configuration (without a prefix: ``Auto``).
* ``UT_Never`` (in configuration: ``Never``)
Never use tab.
* ``UT_ForIndentation`` (in configuration: ``ForIndentation``)
Use tabs only for 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.
.. END_FORMAT_STYLE_OPTIONS
Adding additional style options

199
clang/include/clang/Format/Format.h
View File

@@ -37,10 +37,10 @@ public:
const std::error_category &getParseCategory();
std::error_code make_error_code(ParseError e);
/// \brief The \c FormatStyle is used to configure the formatting to follow
/// \brief The ``FormatStyle`` is used to configure the formatting to follow
/// specific guidelines.
struct FormatStyle {
/// \brief The extra indent or outdent of access modifiers, e.g. \c public:.
/// \brief The extra indent or outdent of access modifiers, e.g. ``public``:.
int AccessModifierOffset;
/// \brief Different styles for aligning after open brackets.
@@ -51,7 +51,7 @@ struct FormatStyle {
/// argument2);
/// \endcode
BAS_Align,
/// \brief Don't align, instead use \c ContinuationIndentWidth, e.g.:
/// \brief Don't align, instead use ``ContinuationIndentWidth``, e.g.:
/// \code
/// someLongFunction(argument1,
/// argument2);
@@ -66,13 +66,13 @@ struct FormatStyle {
BAS_AlwaysBreak,
};
/// \brief If \c true, horizontally aligns arguments after an open bracket.
/// \brief If ``true``, horizontally aligns arguments after an open bracket.
///
/// This applies to round brackets (parentheses), angle brackets and square
/// brackets.
BracketAlignmentStyle AlignAfterOpenBracket;
/// \brief If \c true, aligns consecutive assignments.
/// \brief If ``true``, aligns consecutive assignments.
///
/// This will align the assignment operators of consecutive lines. This
/// will result in formattings like
@@ -83,7 +83,7 @@ struct FormatStyle {
/// \endcode
bool AlignConsecutiveAssignments;
/// \brief If \c true, aligns consecutive declarations.
/// \brief If ``true``, aligns consecutive declarations.
///
/// This will align the declaration names of consecutive lines. This
/// will result in formattings like
@@ -94,11 +94,11 @@ struct FormatStyle {
/// \endcode
bool AlignConsecutiveDeclarations;
/// \brief If \c true, aligns escaped newlines as far left as possible.
/// \brief If ``true``, aligns escaped newlines as far left as possible.
/// Otherwise puts them into the right-most column.
bool AlignEscapedNewlinesLeft;
/// \brief If \c true, horizontally align operands of binary and ternary
/// \brief If ``true``, horizontally align operands of binary and ternary
/// expressions.
///
/// Specifically, this aligns operands of a single expression that needs to be
@@ -109,19 +109,19 @@ struct FormatStyle {
/// \endcode
bool AlignOperands;
/// \brief If \c true, aligns trailing comments.
/// \brief If ``true``, aligns trailing comments.
bool AlignTrailingComments;
/// \brief Allow putting all parameters of a function declaration onto
/// the next line even if \c BinPackParameters is \c false.
/// the next line even if ``BinPackParameters`` is ``false``.
bool AllowAllParametersOfDeclarationOnNextLine;
/// \brief Allows contracting simple braced statements to a single line.
///
/// E.g., this allows <tt>if (a) { return; }</tt> to be put on a single line.
/// E.g., this allows ``if (a) { return; }`` to be put on a single line.
bool AllowShortBlocksOnASingleLine;
/// \brief If \c true, short case labels will be contracted to a single line.
/// \brief If ``true``, short case labels will be contracted to a single line.
bool AllowShortCaseLabelsOnASingleLine;
/// \brief Different styles for merging short functions containing at most one
@@ -137,22 +137,21 @@ struct FormatStyle {
SFS_All,
};
/// \brief Dependent on the value, <tt>int f() { return 0; }</tt> can be put
/// on a single line.
/// \brief Dependent on the value, ``int f() { return 0; }`` can be put on a
/// single line.
ShortFunctionStyle AllowShortFunctionsOnASingleLine;
/// \brief If \c true, <tt>if (a) return;</tt> can be put on a single
/// line.
/// \brief If ``true``, ``if (a) return;`` can be put on a single line.
bool AllowShortIfStatementsOnASingleLine;
/// \brief If \c true, <tt>while (true) continue;</tt> can be put on a
/// single line.
/// \brief If ``true``, ``while (true) continue;`` can be put on a single
/// line.
bool AllowShortLoopsOnASingleLine;
/// \brief Different ways to break after the function definition return type.
enum DefinitionReturnTypeBreakingStyle {
/// Break after return type automatically.
/// \c PenaltyReturnTypeOnItsOwnLine is taken into account.
/// ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
DRTBS_None,
/// Always break after the return type.
DRTBS_All,
@@ -164,7 +163,7 @@ struct FormatStyle {
/// declaration return type.
enum ReturnTypeBreakingStyle {
/// Break after return type automatically.
/// \c PenaltyReturnTypeOnItsOwnLine is taken into account.
/// ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
RTBS_None,
/// Always break after the return type.
RTBS_All,
@@ -183,23 +182,23 @@ struct FormatStyle {
/// \brief The function declaration return type breaking style to use.
ReturnTypeBreakingStyle AlwaysBreakAfterReturnType;
/// \brief If \c true, always break before multiline string literals.
/// \brief If ``true``, always break before multiline string literals.
///
/// This flag is mean to make cases where there are multiple multiline strings
/// in a file look more consistent. Thus, it will only take effect if wrapping
/// the string at that point leads to it being indented
/// \c ContinuationIndentWidth spaces from the start of the line.
/// ``ContinuationIndentWidth`` spaces from the start of the line.
bool AlwaysBreakBeforeMultilineStrings;
/// \brief If \c true, always break after the <tt>template<...></tt> of a
/// template declaration.
/// \brief If ``true``, always break after the ``template<...>`` of a template
/// declaration.
bool AlwaysBreakTemplateDeclarations;
/// \brief If \c false, a function call's arguments will either be all on the
/// \brief If ``false``, a function call's arguments will either be all on the
/// same line or will have one line each.
bool BinPackArguments;
/// \brief If \c false, a function declaration's or function definition's
/// \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.
bool BinPackParameters;
@@ -220,13 +219,14 @@ struct FormatStyle {
enum BraceBreakingStyle {
/// Always attach braces to surrounding context.
BS_Attach,
/// Like \c Attach, but break before braces on function, namespace and
/// Like ``Attach``, but break before braces on function, namespace and
/// class definitions.
BS_Linux,
/// Like ``Attach``, but break before braces on enum, function, and record
/// definitions.
BS_Mozilla,
/// Like \c Attach, but break before function definitions, 'catch', and 'else'.
/// Like ``Attach``, but break before function definitions, ``catch``, and
/// ``else``.
BS_Stroustrup,
/// Always break before braces.
BS_Allman,
@@ -236,7 +236,7 @@ struct FormatStyle {
BS_GNU,
/// Like ``Attach``, but break before functions.
BS_WebKit,
/// Configure each individual brace in \c BraceWrapping.
/// Configure each individual brace in `BraceWrapping`.
BS_Custom
};
@@ -247,7 +247,7 @@ struct FormatStyle {
struct BraceWrappingFlags {
/// \brief Wrap class definitions.
bool AfterClass;
/// \brief Wrap control statements (if/for/while/switch/..).
/// \brief Wrap control statements (``if``/``for``/``while``/``switch``/..).
bool AfterControlStatement;
/// \brief Wrap enum definitions.
bool AfterEnum;
@@ -255,15 +255,15 @@ struct FormatStyle {
bool AfterFunction;
/// \brief Wrap namespace definitions.
bool AfterNamespace;
/// \brief Wrap ObjC definitions (@autoreleasepool, interfaces, ..).
/// \brief Wrap ObjC definitions (``@autoreleasepool``, interfaces, ..).
bool AfterObjCDeclaration;
/// \brief Wrap struct definitions.
bool AfterStruct;
/// \brief Wrap union definitions.
bool AfterUnion;
/// \brief Wrap before \c catch.
/// \brief Wrap before ``catch``.
bool BeforeCatch;
/// \brief Wrap before \c else.
/// \brief Wrap before ``else``.
bool BeforeElse;
/// \brief Indent the wrapped braces themselves.
bool IndentBraces;
@@ -271,11 +271,11 @@ struct FormatStyle {
/// \brief Control of individual brace wrapping cases.
///
/// If \c BreakBeforeBraces is set to \c custom, use this to specify how each
/// individual brace case should be handled. Otherwise, this is ignored.
/// If ``BreakBeforeBraces`` is set to ``BS_Custom``, use this to specify how
/// each individual brace case should be handled. Otherwise, this is ignored.
BraceWrappingFlags BraceWrapping;
/// \brief If \c true, ternary operators will be placed after line breaks.
/// \brief If ``true``, ternary operators will be placed after line breaks.
bool BreakBeforeTernaryOperators;
/// \brief Always break constructor initializers before commas and align
@@ -290,7 +290,7 @@ struct FormatStyle {
/// \brief The column limit.
///
/// A column limit of \c 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
/// statements unless they contradict other rules.
unsigned ColumnLimit;
@@ -310,7 +310,7 @@ struct FormatStyle {
/// \brief Indent width for line continuations.
unsigned ContinuationIndentWidth;
/// \brief If \c true, format braced lists as best suited for C++11 braced
/// \brief If ``true``, format braced lists as best suited for C++11 braced
/// lists.
///
/// Important differences:
@@ -320,19 +320,20 @@ struct FormatStyle {
///
/// Fundamentally, C++11 braced lists are formatted exactly like function
/// calls would be formatted in their place. If the braced list follows a name
/// (e.g. a type or variable name), clang-format formats as if the \c {} were
/// (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.
bool Cpp11BracedListStyle;
/// \brief If \c true, analyze the formatted file for the most common
/// alignment of & and *. \c PointerAlignment is then used only as fallback.
/// \brief If ``true``, analyze the formatted file for the most common
/// alignment of ``&`` and ``*``. ``PointerAlignment`` is then used only as
/// fallback.
bool DerivePointerAlignment;
/// \brief Disables formatting completely.
bool DisableFormat;
/// \brief If \c true, clang-format detects whether function calls and
/// \brief If ``true``, clang-format detects whether function calls and
/// definitions are formatted with one parameter per line.
///
/// Each call can be bin-packed, one-per-line or inconclusive. If it is
@@ -354,14 +355,14 @@ struct FormatStyle {
/// \endcode
///
/// In the .clang-format configuration file, this can be configured like:
/// \code
/// \code{.yaml}
/// ForEachMacros: ['RANGES_FOR', 'FOREACH']
/// \endcode
///
/// For example: BOOST_FOREACH.
std::vector<std::string> ForEachMacros;
/// \brief See documentation of \c IncludeCategories.
/// \brief See documentation of ``IncludeCategories``.
struct IncludeCategory {
/// \brief The regular expression that this category matches.
std::string Regex;
@@ -372,24 +373,24 @@ struct FormatStyle {
}
};
/// \brief Regular expressions denoting the different #include categories used
/// for ordering #includes.
/// \brief Regular expressions denoting the different ``#include`` categories
/// used for ordering ``#includes``.
///
/// These regular expressions are matched against the filename of an include
/// (including the <> or "") in order. The value belonging to the first
/// matching regular expression is assigned and #includes are sorted first
/// matching regular expression is assigned and ``#includes`` are sorted first
/// according to increasing category number and then alphabetically within
/// each category.
///
/// If none of the regular expressions match, INT_MAX is assigned as
/// category. The main header for a source file automatically gets category 0.
/// so that it is generally kept at the beginning of the #includes
/// so that it is generally kept at the beginning of the ``#includes``
/// (http://llvm.org/docs/CodingStandards.html#include-style). However, you
/// can also assign negative priorities if you have certain headers that
/// always need to be first.
///
/// To configure this in the .clang-format file, use:
/// \code
/// \code{.yaml}
/// IncludeCategories:
/// - Regex: '^"(llvm|llvm-c|clang|clang-c)/'
/// Priority: 2
@@ -402,7 +403,7 @@ struct FormatStyle {
/// \brief Indent case labels one level from the switch statement.
///
/// When \c false, use the same indentation level as for the switch statement.
/// When ``false``, use the same indentation level as for the switch statement.
/// Switch statement body is always indented one level more than case labels.
bool IndentCaseLabels;
@@ -416,9 +417,11 @@ struct FormatStyle {
/// \brief If true, empty lines at the start of blocks are kept.
bool KeepEmptyLinesAtTheStartOfBlocks;
/// \brief Supported languages. When stored in a configuration file, specifies
/// the language, that the configuration targets. When passed to the
/// reformat() function, enables syntax features specific to the language.
/// \brief Supported languages.
///
/// When stored in a configuration file, specifies the language, that the
/// configuration targets. When passed to the ``reformat()`` function, enables
/// syntax features specific to the language.
enum LanguageKind {
/// Do not use.
LK_None,
@@ -463,21 +466,21 @@ struct FormatStyle {
/// \brief The number of characters to use for indentation of ObjC blocks.
unsigned ObjCBlockIndentWidth;
/// \brief Add a space after \c @property in Objective-C, i.e. use
/// <tt>\@property (readonly)</tt> instead of <tt>\@property(readonly)</tt>.
/// \brief Add a space after ``@property`` in Objective-C, i.e. use
/// ``@property (readonly)`` instead of ``@property(readonly)``.
bool ObjCSpaceAfterProperty;
/// \brief Add a space in front of an Objective-C protocol list, i.e. use
/// <tt>Foo <Protocol></tt> instead of \c Foo<Protocol>.
/// ``Foo <Protocol>`` instead of ``Foo<Protocol>``.
bool ObjCSpaceBeforeProtocolList;
/// \brief The penalty for breaking a function call after "call(".
/// \brief The penalty for breaking a function call after ``call(``.
unsigned PenaltyBreakBeforeFirstCallParameter;
/// \brief The penalty for each line break introduced inside a comment.
unsigned PenaltyBreakComment;
/// \brief The penalty for breaking before the first \c <<.
/// \brief The penalty for breaking before the first ``<<``.
unsigned PenaltyBreakFirstLessLess;
/// \brief The penalty for each line break introduced inside a string literal.
@@ -490,7 +493,7 @@ struct FormatStyle {
/// line.
unsigned PenaltyReturnTypeOnItsOwnLine;
/// \brief The & and * alignment style.
/// \brief The ``&`` and ``*`` alignment style.
enum PointerAlignmentStyle {
/// Align pointer to the left.
PAS_Left,
@@ -503,16 +506,16 @@ struct FormatStyle {
/// \brief Pointer and reference alignment style.
PointerAlignmentStyle PointerAlignment;
/// \brief If true, clang-format will attempt to re-flow comments.
/// \brief If ``true``, clang-format will attempt to re-flow comments.
bool ReflowComments;
/// \brief If true, clang-format will sort #includes.
/// \brief If ``true``, clang-format will sort ``#includes``.
bool SortIncludes;
/// \brief If \c true, a space may be inserted after C style casts.
/// \brief If ``true``, a space may be inserted after C style casts.
bool SpaceAfterCStyleCast;
/// \brief If \c false, spaces will be removed before assignment operators.
/// \brief If ``false``, spaces will be removed before assignment operators.
bool SpaceBeforeAssignmentOperators;
/// \brief Different ways to put a space before opening parentheses.
@@ -520,7 +523,7 @@ struct FormatStyle {
/// Never put a space before opening parentheses.
SBPO_Never,
/// Put a space before opening parentheses only after control statement
/// keywords (<tt>for/if/while...</tt>).
/// keywords (``for/if/while...``).
SBPO_ControlStatements,
/// Always put a space before opening parentheses, except when it's
/// prohibited by the syntax rules (in function-like macro definitions) or
@@ -532,46 +535,46 @@ struct FormatStyle {
/// \brief Defines in which cases to put a space before opening parentheses.
SpaceBeforeParensOptions SpaceBeforeParens;
/// \brief If \c true, spaces may be inserted into '()'.
/// \brief If ``true``, spaces may be inserted into ``()``.
bool SpaceInEmptyParentheses;
/// \brief The number of spaces before trailing line comments
/// (\c // - comments).
/// (``//`` - comments).
///
/// This does not affect trailing block comments (\c /**/ - comments) as those
/// commonly have different usage patterns and a number of special cases.
/// This does not affect trailing block comments (``/**/`` - comments) as
/// those commonly have different usage patterns and a number of special
/// cases.
unsigned SpacesBeforeTrailingComments;
/// \brief If \c true, spaces will be inserted after '<' and before '>' in
/// template argument lists
/// \brief If ``true``, spaces will be inserted after ``<`` and before ``>``
/// in template argument lists.
bool SpacesInAngles;
/// \brief If \c true, spaces are inserted inside container literals (e.g.
/// \brief If ``true``, spaces are inserted inside container literals (e.g.
/// ObjC and Javascript array and dict literals).
bool SpacesInContainerLiterals;
/// \brief If \c true, spaces may be inserted into C style casts.
/// \brief If ``true``, spaces may be inserted into C style casts.
bool SpacesInCStyleCastParentheses;
/// \brief If \c true, spaces will be inserted after '(' and before ')'.
/// \brief If ``true``, spaces will be inserted after ``(`` and before ``)``.
bool SpacesInParentheses;
/// \brief If \c true, spaces will be inserted after '[' and before ']'.
/// \brief If ``true``, spaces will be inserted after ``[`` and before ``]``.
bool SpacesInSquareBrackets;
/// \brief Supported language standards.
enum LanguageStandard {
/// Use C++03-compatible syntax.
LS_Cpp03,
/// Use features of C++11 (e.g. \c A<A<int>> instead of
/// <tt>A<A<int> ></tt>).
/// Use features of C++11 (e.g. ``A<A<int>>`` instead of ``A<A<int> >``).
LS_Cpp11,
/// Automatic detection based on the input.
LS_Auto
};
/// \brief Format compatible with this standard, e.g. use
/// <tt>A<A<int> ></tt> instead of \c A<A<int>> for LS_Cpp03.
/// \brief Format compatible with this standard, e.g. use ``A<A<int> >``
/// instead of ``A<A<int>>`` for ``LS_Cpp03``.
LanguageStandard Standard;
/// \brief The number of columns used for tab stops.
@@ -705,24 +708,24 @@ FormatStyle getNoStyle();
/// Currently supported names: LLVM, Google, Chromium, Mozilla. Names are
/// compared case-insensitively.
///
/// Returns \c true if the Style has been set.
/// Returns ``true`` if the Style has been set.
bool getPredefinedStyle(StringRef Name, FormatStyle::LanguageKind Language,
FormatStyle *Style);
/// \brief Parse configuration from YAML-formatted text.
///
/// Style->Language is used to get the base style, if the \c BasedOnStyle
/// Style->Language is used to get the base style, if the ``BasedOnStyle``
/// option is present.
///
/// When \c BasedOnStyle is not present, options not present in the YAML
/// When ``BasedOnStyle`` is not present, options not present in the YAML
/// document, are retained in \p Style.
std::error_code parseConfiguration(StringRef Text, FormatStyle *Style);
/// \brief Gets configuration in a YAML string.
std::string configurationAsText(const FormatStyle &Style);
/// \brief Returns the replacements necessary to sort all #include blocks that
/// are affected by 'Ranges'.
/// \brief Returns the replacements necessary to sort all ``#include`` blocks
/// that are affected by ``Ranges``.
tooling::Replacements sortIncludes(const FormatStyle &Style, StringRef Code,
ArrayRef<tooling::Range> Ranges,
StringRef FileName,
@@ -734,10 +737,10 @@ tooling::Replacements sortIncludes(const FormatStyle &Style, StringRef Code,
/// everything that might influence its formatting or might be influenced by its
/// formatting.
///
/// Returns the \c Replacements necessary to make all \p Ranges comply with
/// Returns the ``Replacements`` necessary to make all \p Ranges comply with
/// \p Style.
///
/// If \c IncompleteFormat is non-null, its value will be set to true if any
/// If ``IncompleteFormat`` is non-null, its value will be set to true if any
/// of the affected ranges were not formatted due to a non-recoverable syntax
/// error.
tooling::Replacements reformat(const FormatStyle &Style,
@@ -753,35 +756,35 @@ tooling::Replacements reformat(const FormatStyle &Style, StringRef Code,
StringRef FileName = "<stdin>",
bool *IncompleteFormat = nullptr);
/// \brief Returns the \c LangOpts that the formatter expects you to set.
/// \brief Returns the ``LangOpts`` that the formatter expects you to set.
///
/// \param Style determines specific settings for lexing mode.
LangOptions getFormattingLangOpts(const FormatStyle &Style = getLLVMStyle());
/// \brief Description to be used for help text for a llvm::cl option for
/// \brief Description to be used for help text for a ``llvm::cl`` option for
/// specifying format style. The description is closely related to the operation
/// of getStyle().
/// of ``getStyle()``.
extern const char *StyleOptionHelpDescription;
/// \brief Construct a FormatStyle based on \c StyleName.
/// \brief Construct a FormatStyle based on ``StyleName``.
///
/// \c StyleName can take several forms:
/// \li "{<key>: <value>, ...}" - Set specic style parameters.
/// \li "<style name>" - One of the style names supported by
/// ``StyleName`` can take several forms:
/// * "{<key>: <value>, ...}" - Set specic style parameters.
/// * "<style name>" - One of the style names supported by
/// getPredefinedStyle().
/// \li "file" - Load style configuration from a file called '.clang-format'
/// located in one of the parent directories of \c FileName or the current
/// directory if \c FileName is empty.
/// * "file" - Load style configuration from a file called ``.clang-format``
/// located in one of the parent directories of ``FileName`` or the current
/// directory if ``FileName`` is empty.
///
/// \param[in] StyleName Style name to interpret according to the description
/// above.
/// \param[in] FileName Path to start search for .clang-format if \c StyleName
/// \param[in] FileName Path to start search for .clang-format if ``StyleName``
/// == "file".
/// \param[in] FallbackStyle The name of a predefined style used to fallback to
/// in case the style can't be determined from \p StyleName.
///
/// \returns FormatStyle as specified by \c StyleName. If no style could be
/// determined, the default is LLVM Style (see getLLVMStyle()).
/// \returns FormatStyle as specified by ``StyleName``. If no style could be
/// determined, the default is LLVM Style (see ``getLLVMStyle()``).
FormatStyle getStyle(StringRef StyleName, StringRef FileName,
StringRef FallbackStyle);