Index: contrib/llvm/tools/clang/include/clang/Format/Format.h
===================================================================
--- contrib/llvm/tools/clang/include/clang/Format/Format.h
+++ contrib/llvm/tools/clang/include/clang/Format/Format.h
@@ -37,10 +37,10 @@
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 @@
/// 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 @@
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 @@
/// \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 @@
/// \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 @@
/// \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 if (a) { return; } 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 @@
SFS_All,
};
- /// \brief Dependent on the value, int f() { return 0; } 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, if (a) return; 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, while (true) continue; 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 @@
/// 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 @@
/// \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 template<...> 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 @@
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 @@
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 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 @@
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 @@
/// \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
@@ -285,9 +285,12 @@
/// \brief Break after each annotation on a field in Java files.
bool BreakAfterJavaFieldAnnotations;
+ /// \brief Allow breaking string literals when formatting.
+ bool BreakStringLiterals;
+
/// \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;
@@ -307,7 +310,7 @@
/// \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:
@@ -317,19 +320,20 @@
///
/// 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
@@ -351,14 +355,14 @@
/// \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 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;
@@ -369,24 +373,24 @@
}
};
- /// \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
@@ -399,7 +403,7 @@
/// \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;
@@ -413,9 +417,11 @@
/// \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,
@@ -460,21 +466,21 @@
/// \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
- /// \@property (readonly) instead of \@property(readonly).
+ /// \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
- /// Foo instead of \c Foo.
+ /// ``Foo `` instead of ``Foo``.
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.
@@ -487,7 +493,7 @@
/// line.
unsigned PenaltyReturnTypeOnItsOwnLine;
- /// \brief The & and * alignment style.
+ /// \brief The ``&`` and ``*`` alignment style.
enum PointerAlignmentStyle {
/// Align pointer to the left.
PAS_Left,
@@ -500,16 +506,16 @@
/// \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.
@@ -517,7 +523,7 @@
/// Never put a space before opening parentheses.
SBPO_Never,
/// Put a space before opening parentheses only after control statement
- /// keywords (for/if/while...).
+ /// 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
@@ -529,46 +535,46 @@
/// \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> instead of
- /// A >).
+ /// Use features of C++11 (e.g. ``A>`` instead of ``A >``).
LS_Cpp11,
/// Automatic detection based on the input.
LS_Auto
};
- /// \brief Format compatible with this standard, e.g. use
- /// A > instead of \c A> for LS_Cpp03.
+ /// \brief Format compatible with this standard, e.g. use ``A >``
+ /// instead of ``A>`` for ``LS_Cpp03``.
LanguageStandard Standard;
/// \brief The number of columns used for tab stops.
@@ -588,6 +594,20 @@
/// \brief The way to use tab characters in the resulting file.
UseTabStyle UseTab;
+ /// \brief Quotation styles for JavaScript strings. Does not affect template
+ /// strings.
+ enum JavaScriptQuoteStyle {
+ /// Leave string quotes as they are.
+ JSQS_Leave,
+ /// Always use single quotes.
+ JSQS_Single,
+ /// Always use double quotes.
+ JSQS_Double
+ };
+
+ /// \brief The JavaScriptQuoteStyle to use for JavaScript strings.
+ JavaScriptQuoteStyle JavaScriptQuotes;
+
bool operator==(const FormatStyle &R) const {
return AccessModifierOffset == R.AccessModifierOffset &&
AlignAfterOpenBracket == R.AlignAfterOpenBracket &&
@@ -619,6 +639,7 @@
BreakConstructorInitializersBeforeComma ==
R.BreakConstructorInitializersBeforeComma &&
BreakAfterJavaFieldAnnotations == R.BreakAfterJavaFieldAnnotations &&
+ BreakStringLiterals == R.BreakStringLiterals &&
ColumnLimit == R.ColumnLimit && CommentPragmas == R.CommentPragmas &&
ConstructorInitializerAllOnOneLineOrOnePerLine ==
R.ConstructorInitializerAllOnOneLineOrOnePerLine &&
@@ -663,7 +684,8 @@
SpacesInParentheses == R.SpacesInParentheses &&
SpacesInSquareBrackets == R.SpacesInSquareBrackets &&
Standard == R.Standard && TabWidth == R.TabWidth &&
- UseTab == R.UseTab;
+ UseTab == R.UseTab &&
+ JavaScriptQuotes == R.JavaScriptQuotes;
}
};
@@ -701,39 +723,61 @@
/// 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 Ranges,
StringRef FileName,
unsigned *Cursor = nullptr);
+/// \brief Returns the replacements corresponding to applying and formatting
+/// \p Replaces.
+tooling::Replacements formatReplacements(StringRef Code,
+ const tooling::Replacements &Replaces,
+ const FormatStyle &Style);
+
+/// \brief In addition to applying all replacements in \p Replaces to \p Code,
+/// this function also reformats the changed code after applying replacements.
+///
+/// \pre Replacements must be for the same file and conflict-free.
+///
+/// Replacement applications happen independently of the success of
+/// other applications.
+///
+/// \returns the changed code with all replacements applied and formatted, if
+/// successful. An empty string otherwise.
+///
+/// See also "include/clang/Tooling/Core/Replacements.h".
+std::string applyAllReplacementsAndFormat(StringRef Code,
+ const tooling::Replacements &Replaces,
+ const FormatStyle &Style);
+
/// \brief Reformats the given \p Ranges in the file \p ID.
///
/// Each range is extended on either end to its next bigger logic unit, i.e.
/// 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,
@@ -749,35 +793,35 @@
StringRef FileName = "",
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 "{: , ...}" - Set specic style parameters.
-/// \li "