sylvestre.ledru created this revision.
Herald added a subscriber: klimek.
https://reviews.llvm.org/D30990
Files:
docs/ClangFormatStyleOptions.rst
include/clang/Format/Format.h
Index: include/clang/Format/Format.h
===================================================================
--- include/clang/Format/Format.h
+++ include/clang/Format/Format.h
@@ -204,7 +204,7 @@
bool AllowShortLoopsOnASingleLine;
/// \brief Different ways to break after the function definition return type.
- /// This option is deprecated and is retained for backwards compatibility.
+ /// This option is **deprecated** and is retained for backwards compatibility.
enum DefinitionReturnTypeBreakingStyle {
/// Break after return type automatically.
/// ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
@@ -287,7 +287,7 @@
};
/// \brief The function definition return type breaking style to use. This
- /// option is deprecated and is retained for backwards compatibility.
+ /// option is **deprecated** and is retained for backwards compatibility.
DefinitionReturnTypeBreakingStyle AlwaysBreakAfterDefinitionReturnType;
/// \brief The function declaration return type breaking style to use.
@@ -318,19 +318,73 @@
/// \brief If ``false``, a function call's arguments will either be all on the
/// same line or will have one line each.
+ /// \code
+ /// true:
+ /// void f() {
+ /// f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa,
+ /// aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
+ /// }
+ ///
+ /// false:
+ /// void f() {
+ /// f(aaaaaaaaaaaaaaaaaaaa,
+ /// aaaaaaaaaaaaaaaaaaaa,
+ /// aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
+ /// }
+ /// \endcode
bool BinPackArguments;
/// \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.
+ /// \code
+ /// true:
+ /// void f(int aaaaaaaaaaaaaaaaaaaa, int aaaaaaaaaaaaaaaaaaaa,
+ /// int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
+ ///
+ /// false:
+ /// void f(int aaaaaaaaaaaaaaaaaaaa,
+ /// int aaaaaaaaaaaaaaaaaaaa,
+ /// int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
+ /// \endcode
bool BinPackParameters;
/// \brief The style of breaking before or after binary operators.
enum BinaryOperatorStyle {
/// Break after operators.
+ /// \code
+ /// LooooooooooongType loooooooooooooooooooooongVariable =
+ /// someLooooooooooooooooongFunction();
+ ///
+ /// bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +
+ /// aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa ==
+ /// aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa &&
+ /// aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa >
+ /// ccccccccccccccccccccccccccccccccccccccccc;
+ /// \endcode
BOS_None,
/// Break before operators that aren't assignments.
+ /// \code
+ /// LooooooooooongType loooooooooooooooooooooongVariable =
+ /// someLooooooooooooooooongFunction();
+ ///
+ /// bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ /// + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ /// == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ /// && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ /// > ccccccccccccccccccccccccccccccccccccccccc;
+ /// \endcode
BOS_NonAssignment,
/// Break before operators.
+ /// \code
+ /// LooooooooooongType loooooooooooooooooooooongVariable
+ /// = someLooooooooooooooooongFunction();
+ ///
+ /// bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ /// + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ /// == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ /// && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ /// > ccccccccccccccccccccccccccccccccccccccccc;
+ /// \endcode
BOS_All,
};
@@ -665,6 +719,11 @@
/// \brief A regular expression that describes comments with special meaning,
/// which should not be split into lines or otherwise changed.
+ /// \code
+ /// CommentPragmas: '^ FOOBAR pragma:'
+ /// // Will leave the following line unaffected
+ /// #include <vector> // FOOBAR pragma: keep
+ /// \endcode
std::string CommentPragmas;
/// \brief If ``true``, in the class inheritance expression clang-format will
@@ -824,6 +883,15 @@
bool IndentCaseLabels;
/// \brief The number of columns to use for indentation.
+ /// \code
+ /// IndentWidth: 3
+ /// void f() {
+ /// someFunction();
+ /// if (true, false) {
+ /// f();
+ /// }
+ /// }
+ /// \endcode
unsigned IndentWidth;
/// \brief Indent if a function definition or declaration is wrapped after the
@@ -878,6 +946,32 @@
LanguageKind Language;
/// \brief A regular expression matching macros that start a block.
+ /// \code
+ /// # With:
+ /// MacroBlockBegin: "^\
+ /// NS_MAP_BEGIN|\
+ /// NS_TABLE_HEAD$"
+ /// MacroBlockEnd: "^\
+ /// NS_MAP_END|\
+ /// NS_TABLE_.*_END$"
+ ///
+ /// NS_MAP_BEGIN
+ /// foo();
+ /// NS_MAP_END
+ ///
+ /// NS_TABLE_HEAD
+ /// bar();
+ /// NS_TABLE_FOO_END
+ ///
+ /// # Without:
+ /// NS_MAP_BEGIN
+ /// foo();
+ /// NS_MAP_END
+ ///
+ /// NS_TABLE_HEAD
+ /// bar();
+ /// NS_TABLE_FOO_END
+ /// \endcode
std::string MacroBlockBegin;
/// \brief A regular expression matching macros that end a block.
@@ -884,15 +978,49 @@
std::string MacroBlockEnd;
/// \brief The maximum number of consecutive empty lines to keep.
+ /// \code
+ /// MaxEmptyLinesToKeep: 1 vs. MaxEmptyLinesToKeep: 1
+ /// int f() { int f() {
+ /// int = 1; int i = 1;
+ /// i = foo();
+ /// i = foo(); return i;
+ /// }
+ /// return i;
+ /// }
+ /// \endcode
unsigned MaxEmptyLinesToKeep;
/// \brief Different ways to indent namespace contents.
enum NamespaceIndentationKind {
/// Don't indent in namespaces.
+ /// \code
+ /// namespace out {
+ /// int i;
+ /// namespace in {
+ /// int i;
+ /// }
+ /// }
+ /// \endcode
NI_None,
/// Indent only in inner namespaces (nested in other namespaces).
+ /// \code
+ /// namespace out {
+ /// int i;
+ /// namespace in {
+ /// int i;
+ /// }
+ /// }
+ /// \endcode
NI_Inner,
/// Indent in all namespaces.
+ /// \code
+ /// namespace out {
+ /// int i;
+ /// namespace in {
+ /// int i;
+ /// }
+ /// }
+ /// \endcode
NI_All
};
@@ -952,6 +1080,17 @@
PointerAlignmentStyle PointerAlignment;
/// \brief If ``true``, clang-format will attempt to re-flow comments.
+ /// \code
+ /// false:
+ /// // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
+ /// /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
+ ///
+ /// true:
+ /// // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
+ /// // information
+ /// /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
+ /// * information */
+ /// \endcode
bool ReflowComments;
/// \brief If ``true``, clang-format will sort ``#includes``.
@@ -987,14 +1126,35 @@
/// \brief Different ways to put a space before opening parentheses.
enum SpaceBeforeParensOptions {
/// Never put a space before opening parentheses.
+ /// \code
+ /// void f() {
+ /// if(true) {
+ /// f();
+ /// }
+ /// }
+ /// \endcode
SBPO_Never,
/// Put a space before opening parentheses only after control statement
/// keywords (``for/if/while...``).
+ /// \code
+ /// void f() {
+ /// if (true) {
+ /// f();
+ /// }
+ /// }
+ /// \endcode
SBPO_ControlStatements,
/// Always put a space before opening parentheses, except when it's
/// prohibited by the syntax rules (in function-like macro definitions) or
/// when determined by other style rules (after unary operators, opening
/// parentheses, etc.)
+ /// \code
+ /// void f () {
+ /// if (true) {
+ /// f ();
+ /// }
+ /// }
+ /// \endcode
SBPO_Always
};
@@ -1002,6 +1162,23 @@
SpaceBeforeParensOptions SpaceBeforeParens;
/// \brief If ``true``, spaces may be inserted into ``()``.
+ /// \code
+ /// true:
+ /// void f( ) {
+ /// int x[] = {foo( ), bar( )};
+ /// if (true) {
+ /// f( );
+ /// }
+ /// }
+ ///
+ /// false:
+ /// void f() {
+ /// int x[] = {foo(), bar()};
+ /// if (true) {
+ /// f();
+ /// }
+ /// }
+ /// \endcode
bool SpaceInEmptyParentheses;
/// \brief The number of spaces before trailing line comments
@@ -1010,6 +1187,14 @@
/// This does not affect trailing block comments (``/*`` - comments) as
/// those commonly have different usage patterns and a number of special
/// cases.
+ /// \code
+ /// SpacesBeforeTrailingComments: 3
+ /// void f() {
+ /// if (true) { // foo1
+ /// f(); // bar
+ /// } // foo
+ /// }
+ /// \endcode
unsigned SpacesBeforeTrailingComments;
/// \brief If ``true``, spaces will be inserted after ``<`` and before ``>``
Index: docs/ClangFormatStyleOptions.rst
===================================================================
--- docs/ClangFormatStyleOptions.rst
+++ docs/ClangFormatStyleOptions.rst
@@ -327,7 +327,7 @@
**AlwaysBreakAfterDefinitionReturnType** (``DefinitionReturnTypeBreakingStyle``)
The function definition return type breaking style to use. This
- option is deprecated and is retained for backwards compatibility.
+ option is **deprecated** and is retained for backwards compatibility.
Possible values:
@@ -455,10 +455,36 @@
If ``false``, a function call's arguments will either be all on the
same line or will have one line each.
+ .. code-block:: c++
+
+ true:
+ void f() {
+ f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa,
+ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
+ }
+
+ false:
+ void f() {
+ f(aaaaaaaaaaaaaaaaaaaa,
+ aaaaaaaaaaaaaaaaaaaa,
+ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
+ }
+
**BinPackParameters** (``bool``)
If ``false``, a function declaration's or function definition's
parameters will either all be on the same line or will have one line each.
+ .. code-block:: c++
+
+ true:
+ void f(int aaaaaaaaaaaaaaaaaaaa, int aaaaaaaaaaaaaaaaaaaa,
+ int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
+
+ false:
+ void f(int aaaaaaaaaaaaaaaaaaaa,
+ int aaaaaaaaaaaaaaaaaaaa,
+ int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
+
**BraceWrapping** (``BraceWrappingFlags``)
Control of individual brace wrapping cases.
@@ -623,14 +649,47 @@
* ``BOS_None`` (in configuration: ``None``)
Break after operators.
+ .. code-block:: c++
+
+ LooooooooooongType loooooooooooooooooooooongVariable =
+ someLooooooooooooooooongFunction();
+
+ bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +
+ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa ==
+ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa &&
+ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa >
+ ccccccccccccccccccccccccccccccccccccccccc;
+
* ``BOS_NonAssignment`` (in configuration: ``NonAssignment``)
Break before operators that aren't assignments.
+ .. code-block:: c++
+
+ LooooooooooongType loooooooooooooooooooooongVariable =
+ someLooooooooooooooooongFunction();
+
+ bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ > ccccccccccccccccccccccccccccccccccccccccc;
+
* ``BOS_All`` (in configuration: ``All``)
Break before operators.
+ .. code-block:: c++
+ LooooooooooongType loooooooooooooooooooooongVariable
+ = someLooooooooooooooooongFunction();
+ bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ > ccccccccccccccccccccccccccccccccccccccccc;
+
+
+
**BreakBeforeBraces** (``BraceBreakingStyle``)
The brace breaking style to use.
@@ -837,6 +896,12 @@
A regular expression that describes comments with special meaning,
which should not be split into lines or otherwise changed.
+ .. code-block:: c++
+
+ CommentPragmas: '^ FOOBAR pragma:'
+ // Will leave the following line unaffected
+ #include <vector> // FOOBAR pragma: keep
+
**ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``)
If the constructor initializers don't fit on a line, put each
initializer on its own line.
@@ -979,8 +1044,18 @@
**IndentWidth** (``unsigned``)
The number of columns to use for indentation.
+ .. code-block:: c++
+
+ IndentWidth: 3
+ void f() {
+ someFunction();
+ if (true, false) {
+ f();
+ }
+ }
+
**IndentWrappedFunctionNames** (``bool``)
- Indent if a function definition or declaration is wrapped after the
+ Indent if a function definition or declaration is wrapped afte the
type.
**JavaScriptQuotes** (``JavaScriptQuoteStyle``)
@@ -1037,6 +1112,33 @@
**MacroBlockBegin** (``std::string``)
A regular expression matching macros that start a block.
+ .. code-block:: c++
+
+ # With:
+ MacroBlockBegin: "^\
+ NS_MAP_BEGIN|\
+ NS_TABLE_HEAD$"
+ MacroBlockEnd: "^\
+ NS_MAP_END|\
+ NS_TABLE_.*_END$"
+
+ NS_MAP_BEGIN
+ foo();
+ NS_MAP_END
+
+ NS_TABLE_HEAD
+ bar();
+ NS_TABLE_FOO_END
+
+ # Without:
+ NS_MAP_BEGIN
+ foo();
+ NS_MAP_END
+
+ NS_TABLE_HEAD
+ bar();
+ NS_TABLE_FOO_END
+
**MacroBlockEnd** (``std::string``)
A regular expression matching macros that end a block.
@@ -1043,6 +1145,17 @@
**MaxEmptyLinesToKeep** (``unsigned``)
The maximum number of consecutive empty lines to keep.
+ .. code-block:: c++
+
+ MaxEmptyLinesToKeep: 1 vs. MaxEmptyLinesToKeep: 1
+ int f() { int f() {
+ int = 1; int i = 1;
+ i = foo();
+ i = foo(); return i;
+ }
+ return i;
+ }
+
**NamespaceIndentation** (``NamespaceIndentationKind``)
The indentation used for namespaces.
@@ -1051,14 +1164,41 @@
* ``NI_None`` (in configuration: ``None``)
Don't indent in namespaces.
+ .. code-block:: c++
+
+ namespace out {
+ int i;
+ namespace in {
+ int i;
+ }
+ }
+
* ``NI_Inner`` (in configuration: ``Inner``)
Indent only in inner namespaces (nested in other namespaces).
+ .. code-block:: c++
+
+ namespace out {
+ int i;
+ namespace in {
+ int i;
+ }
+ }
+
* ``NI_All`` (in configuration: ``All``)
Indent in all namespaces.
+ .. code-block:: c++
+ namespace out {
+ int i;
+ namespace in {
+ int i;
+ }
+ }
+
+
**ObjCBlockIndentWidth** (``unsigned``)
The number of characters to use for indentation of ObjC blocks.
@@ -1120,6 +1260,18 @@
**ReflowComments** (``bool``)
If ``true``, clang-format will attempt to re-flow comments.
+ .. code-block:: c++
+
+ false:
+ // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
+ /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
+
+ true:
+ // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
+ // information
+ /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
+ * information */
+
**SortIncludes** (``bool``)
If ``true``, clang-format will sort ``#includes``.
@@ -1162,10 +1314,26 @@
* ``SBPO_Never`` (in configuration: ``Never``)
Never put a space before opening parentheses.
+ .. code-block:: c++
+
+ void f() {
+ if(true) {
+ f();
+ }
+ }
+
* ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``)
Put a space before opening parentheses only after control statement
keywords (``for/if/while...``).
+ .. code-block:: c++
+
+ void f() {
+ if (true) {
+ f();
+ }
+ }
+
* ``SBPO_Always`` (in configuration: ``Always``)
Always put a space before opening parentheses, except when it's
prohibited by the syntax rules (in function-like macro definitions) or
@@ -1172,11 +1340,37 @@
when determined by other style rules (after unary operators, opening
parentheses, etc.)
+ .. code-block:: c++
+ void f () {
+ if (true) {
+ f ();
+ }
+ }
+
+
**SpaceInEmptyParentheses** (``bool``)
If ``true``, spaces may be inserted into ``()``.
+ .. code-block:: c++
+
+ true:
+ void f( ) {
+ int x[] = {foo( ), bar( )};
+ if (true) {
+ f( );
+ }
+ }
+
+ false:
+ void f() {
+ int x[] = {foo(), bar()};
+ if (true) {
+ f();
+ }
+ }
+
**SpacesBeforeTrailingComments** (``unsigned``)
The number of spaces before trailing line comments
(``//`` - comments).
@@ -1185,6 +1379,15 @@
those commonly have different usage patterns and a number of special
cases.
+ .. code-block:: c++
+
+ SpacesBeforeTrailingComments: 3
+ void f() {
+ if (true) { // foo1
+ f(); // bar
+ } // foo
+ }
+
**SpacesInAngles** (``bool``)
If ``true``, spaces will be inserted after ``<`` and before ``>``
in template argument lists.
@@ -1376,4 +1579,3 @@
r();
}
}
-
_______________________________________________
cfe-commits mailing list
[email protected]
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
