r261645 - Clean up clang-format options documentation. NFC
Alexander Kornienko via cfe-commits
cfe-commits at lists.llvm.org
Tue Feb 23 08:12:02 PST 2016
Author: alexfh
Date: Tue Feb 23 10:12:00 2016
New Revision: 261645
URL: http://llvm.org/viewvc/llvm-project?rev=261645&view=rev
Log:
Clean up clang-format options documentation. NFC
Use uniform style for inline code blocks, specify language for YAML code blocks,
various formatting fixes etc.
Modified:
cfe/trunk/docs/ClangFormatStyleOptions.rst
cfe/trunk/include/clang/Format/Format.h
Modified: cfe/trunk/docs/ClangFormatStyleOptions.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/ClangFormatStyleOptions.rst?rev=261645&r1=261644&r2=261645&view=diff
==============================================================================
--- cfe/trunk/docs/ClangFormatStyleOptions.rst (original)
+++ cfe/trunk/docs/ClangFormatStyleOptions.rst Tue Feb 23 10:12:00 2016
@@ -148,7 +148,7 @@ the configuration (without a prefix: ``A
.. 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: ``A
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: ``A
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: ``A
argument1, argument2);
+
**AlignConsecutiveAssignments** (``bool``)
If ``true``, aligns consecutive assignments.
@@ -238,28 +241,31 @@ the configuration (without a prefix: ``A
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: ``A
* ``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: ``A
* ``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: ``A
``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: ``A
**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: ``A
* ``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: ``A
* ``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: ``A
**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: ``A
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: ``A
* ``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: ``A
* ``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: ``A
* ``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: ``A
* ``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: ``A
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: ``A
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: ``A
* ``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
Modified: cfe/trunk/include/clang/Format/Format.h
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Format/Format.h?rev=261645&r1=261644&r2=261645&view=diff
==============================================================================
--- cfe/trunk/include/clang/Format/Format.h (original)
+++ cfe/trunk/include/clang/Format/Format.h Tue Feb 23 10:12:00 2016
@@ -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
/// 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 For
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);
More information about the cfe-commits
mailing list