Author: sylvestre Date: Mon Mar 13 09:42:47 2017 New Revision: 297623 URL: http://llvm.org/viewvc/llvm-project?rev=297623&view=rev Log: [clang-format] Add more examples and fix a bug in the py generation script
Reviewers: djasper Reviewed By: djasper Subscribers: cfe-commits, klimek Differential Revision: https://reviews.llvm.org/D30860 Modified: cfe/trunk/docs/ClangFormatStyleOptions.rst cfe/trunk/docs/tools/dump_format_style.py 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=297623&r1=297622&r2=297623&view=diff ============================================================================== --- cfe/trunk/docs/ClangFormatStyleOptions.rst (original) +++ cfe/trunk/docs/ClangFormatStyleOptions.rst Mon Mar 13 09:42:47 2017 @@ -252,6 +252,13 @@ the configuration (without a prefix: ``A Allow putting all parameters of a function declaration onto the next line even if ``BinPackParameters`` is ``false``. + .. code-block:: c++ + + true: false: + myFunction(foo, vs. myFunction(foo, bar, plop); + bar, + plop); + **AllowShortBlocksOnASingleLine** (``bool``) Allows contracting simple braced statements to a single line. @@ -460,16 +467,148 @@ the configuration (without a prefix: ``A Nested configuration flags: + * ``bool AfterClass`` Wrap class definitions. + + .. code-block:: c++ + + true: + class foo {}; + + false: + class foo + {}; + * ``bool AfterControlStatement`` Wrap control statements (``if``/``for``/``while``/``switch``/..). + + .. code-block:: c++ + + true: + if (foo()) + { + } else + {} + for (int i = 0; i < 10; ++i) + {} + + false: + if (foo()) { + } else { + } + for (int i = 0; i < 10; ++i) { + } + * ``bool AfterEnum`` Wrap enum definitions. + + .. code-block:: c++ + + true: + enum X : int + { + B + }; + + false: + enum X : int { B }; + * ``bool AfterFunction`` Wrap function definitions. + + .. code-block:: c++ + + true: + void foo() + { + bar(); + bar2(); + } + + false: + void foo() { + bar(); + bar2(); + } + * ``bool AfterNamespace`` Wrap namespace definitions. + + .. code-block:: c++ + + true: + namespace + { + int foo(); + int bar(); + } + + false: + namespace { + int foo(); + int bar(); + } + * ``bool AfterObjCDeclaration`` Wrap ObjC definitions (``@autoreleasepool``, interfaces, ..). + * ``bool AfterStruct`` Wrap struct definitions. + + .. code-block:: c++ + + true: + struct foo + { + int x; + } + + false: + struct foo { + int x; + } + * ``bool AfterUnion`` Wrap union definitions. + + .. code-block:: c++ + + true: + union foo + { + int x; + } + + false: + union foo { + int x; + } + * ``bool BeforeCatch`` Wrap before ``catch``. + + .. code-block:: c++ + + true: + try { + foo(); + } + catch () { + } + + false: + try { + foo(); + } catch () { + } + * ``bool BeforeElse`` Wrap before ``else``. + + .. code-block:: c++ + + true: + if (foo()) { + } + else { + } + + false: + if (foo()) { + } else { + } + * ``bool IndentBraces`` Indent the wrapped braces themselves. @@ -500,29 +639,146 @@ the configuration (without a prefix: ``A * ``BS_Attach`` (in configuration: ``Attach``) Always attach braces to surrounding context. + .. code-block:: c++ + + try { + foo(); + } catch () { + } + void foo() { bar(); } + class foo {}; + if (foo()) { + } else { + } + enum X : int { A, B }; + * ``BS_Linux`` (in configuration: ``Linux``) Like ``Attach``, but break before braces on function, namespace and class definitions. + .. code-block:: c++ + + try { + foo(); + } catch () { + } + void foo() { bar(); } + class foo + { + }; + if (foo()) { + } else { + } + enum X : int { A, B }; + * ``BS_Mozilla`` (in configuration: ``Mozilla``) Like ``Attach``, but break before braces on enum, function, and record definitions. + .. code-block:: c++ + + try { + foo(); + } catch () { + } + void foo() { bar(); } + class foo + { + }; + if (foo()) { + } else { + } + enum X : int { A, B }; + * ``BS_Stroustrup`` (in configuration: ``Stroustrup``) Like ``Attach``, but break before function definitions, ``catch``, and ``else``. + .. code-block:: c++ + + try { + foo(); + } catch () { + } + void foo() { bar(); } + class foo + { + }; + if (foo()) { + } else { + } + enum X : int + { + A, + B + }; + * ``BS_Allman`` (in configuration: ``Allman``) Always break before braces. + .. code-block:: c++ + + try { + foo(); + } + catch () { + } + void foo() { bar(); } + class foo { + }; + if (foo()) { + } + else { + } + enum X : int { A, B }; + * ``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. + .. code-block:: c++ + + try + { + foo(); + } + catch () + { + } + void foo() { bar(); } + class foo + { + }; + if (foo()) + { + } + else + { + } + enum X : int + { + A, + B + }; + * ``BS_WebKit`` (in configuration: ``WebKit``) Like ``Attach``, but break before functions. + .. code-block:: c++ + + try { + foo(); + } catch () { + } + void foo() { bar(); } + class foo { + }; + if (foo()) { + } else { + } + enum X : int { A, B }; + * ``BS_Custom`` (in configuration: ``Custom``) Configure each individual brace in `BraceWrapping`. @@ -532,9 +788,29 @@ the configuration (without a prefix: ``A If ``true``, in the class inheritance expression clang-format will break before ``:`` and ``,`` if there is multiple inheritance. + .. code-block:: c++ + + true: false: + class MyClass vs. class MyClass : public X, public Y { + : public X }; + , public Y { + }; + **BreakBeforeTernaryOperators** (``bool``) If ``true``, ternary operators will be placed after line breaks. + .. code-block:: c++ + + true: + veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription + ? firstValue + : SecondValueVeryVeryVeryVeryLong; + + true: + veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription ? + firstValue : + SecondValueVeryVeryVeryVeryLong; + **BreakConstructorInitializersBeforeComma** (``bool``) Always break constructor initializers before commas and align the commas with the colon. @@ -565,6 +841,21 @@ the configuration (without a prefix: ``A If the constructor initializers don't fit on a line, put each initializer on its own line. + .. code-block:: c++ + + true: + SomeClass::Constructor() + : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) { + return 0; + } + + false: + SomeClass::Constructor() + : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa), + aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) { + return 0; + } + **ConstructorInitializerIndentWidth** (``unsigned``) The number of characters to use for indentation of constructor initializer lists. Modified: cfe/trunk/docs/tools/dump_format_style.py URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/tools/dump_format_style.py?rev=297623&r1=297622&r2=297623&view=diff ============================================================================== --- cfe/trunk/docs/tools/dump_format_style.py (original) +++ cfe/trunk/docs/tools/dump_format_style.py Mon Mar 13 09:42:47 2017 @@ -64,7 +64,7 @@ class NestedField: self.comment = comment.strip() def __str__(self): - return '* ``%s`` %s' % (self.name, doxygen2rst(self.comment)) + return '\n* ``%s`` %s' % (self.name, doxygen2rst(self.comment)) class Enum: def __init__(self, name, comment): Modified: cfe/trunk/include/clang/Format/Format.h URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Format/Format.h?rev=297623&r1=297622&r2=297623&view=diff ============================================================================== --- cfe/trunk/include/clang/Format/Format.h (original) +++ cfe/trunk/include/clang/Format/Format.h Mon Mar 13 09:42:47 2017 @@ -136,6 +136,12 @@ struct FormatStyle { /// \brief Allow putting all parameters of a function declaration onto /// the next line even if ``BinPackParameters`` is ``false``. + /// \code + /// true: false: + /// myFunction(foo, vs. myFunction(foo, bar, plop); + /// bar, + /// plop); + /// \endcode bool AllowAllParametersOfDeclarationOnNextLine; /// \brief Allows contracting simple braced statements to a single line. @@ -334,23 +340,133 @@ struct FormatStyle { /// \brief Different ways to attach braces to their surrounding context. enum BraceBreakingStyle { /// Always attach braces to surrounding context. + /// \code + /// try { + /// foo(); + /// } catch () { + /// } + /// void foo() { bar(); } + /// class foo {}; + /// if (foo()) { + /// } else { + /// } + /// enum X : int { A, B }; + /// \endcode BS_Attach, /// Like ``Attach``, but break before braces on function, namespace and /// class definitions. + /// \code + /// try { + /// foo(); + /// } catch () { + /// } + /// void foo() { bar(); } + /// class foo + /// { + /// }; + /// if (foo()) { + /// } else { + /// } + /// enum X : int { A, B }; + /// \endcode BS_Linux, /// Like ``Attach``, but break before braces on enum, function, and record /// definitions. + /// \code + /// try { + /// foo(); + /// } catch () { + /// } + /// void foo() { bar(); } + /// class foo + /// { + /// }; + /// if (foo()) { + /// } else { + /// } + /// enum X : int { A, B }; + /// \endcode BS_Mozilla, /// Like ``Attach``, but break before function definitions, ``catch``, and /// ``else``. + /// \code + /// try { + /// foo(); + /// } catch () { + /// } + /// void foo() { bar(); } + /// class foo + /// { + /// }; + /// if (foo()) { + /// } else { + /// } + /// enum X : int + /// { + /// A, + /// B + /// }; + /// \endcode BS_Stroustrup, /// Always break before braces. + /// \code + /// try { + /// foo(); + /// } + /// catch () { + /// } + /// void foo() { bar(); } + /// class foo { + /// }; + /// if (foo()) { + /// } + /// else { + /// } + /// enum X : int { A, B }; + /// \endcode BS_Allman, /// 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. + /// \code + /// try + /// { + /// foo(); + /// } + /// catch () + /// { + /// } + /// void foo() { bar(); } + /// class foo + /// { + /// }; + /// if (foo()) + /// { + /// } + /// else + /// { + /// } + /// enum X : int + /// { + /// A, + /// B + /// }; + /// \endcode BS_GNU, /// Like ``Attach``, but break before functions. + /// \code + /// try { + /// foo(); + /// } catch () { + /// } + /// void foo() { bar(); } + /// class foo { + /// }; + /// if (foo()) { + /// } else { + /// } + /// enum X : int { A, B }; + /// \endcode BS_WebKit, /// Configure each individual brace in `BraceWrapping`. BS_Custom @@ -360,26 +476,144 @@ struct FormatStyle { BraceBreakingStyle BreakBeforeBraces; /// \brief Precise control over the wrapping of braces. + /// \code + /// # Should be declared this way: + /// BreakBeforeBraces: Custom + /// BraceWrapping: + /// AfterClass: true + /// \endcode struct BraceWrappingFlags { /// \brief Wrap class definitions. + /// \code + /// true: + /// class foo {}; + /// + /// false: + /// class foo + /// {}; + /// \endcode bool AfterClass; /// \brief Wrap control statements (``if``/``for``/``while``/``switch``/..). + /// \code + /// true: + /// if (foo()) + /// { + /// } else + /// {} + /// for (int i = 0; i < 10; ++i) + /// {} + /// + /// false: + /// if (foo()) { + /// } else { + /// } + /// for (int i = 0; i < 10; ++i) { + /// } + /// \endcode bool AfterControlStatement; /// \brief Wrap enum definitions. + /// \code + /// true: + /// enum X : int + /// { + /// B + /// }; + /// + /// false: + /// enum X : int { B }; + /// \endcode bool AfterEnum; /// \brief Wrap function definitions. + /// \code + /// true: + /// void foo() + /// { + /// bar(); + /// bar2(); + /// } + /// + /// false: + /// void foo() { + /// bar(); + /// bar2(); + /// } + /// \endcode bool AfterFunction; /// \brief Wrap namespace definitions. + /// \code + /// true: + /// namespace + /// { + /// int foo(); + /// int bar(); + /// } + /// + /// false: + /// namespace { + /// int foo(); + /// int bar(); + /// } + /// \endcode bool AfterNamespace; /// \brief Wrap ObjC definitions (``@autoreleasepool``, interfaces, ..). bool AfterObjCDeclaration; /// \brief Wrap struct definitions. + /// \code + /// true: + /// struct foo + /// { + /// int x; + /// } + /// + /// false: + /// struct foo { + /// int x; + /// } + /// \endcode bool AfterStruct; /// \brief Wrap union definitions. + /// \code + /// true: + /// union foo + /// { + /// int x; + /// } + /// + /// false: + /// union foo { + /// int x; + /// } + /// \endcode bool AfterUnion; /// \brief Wrap before ``catch``. + /// \code + /// true: + /// try { + /// foo(); + /// } + /// catch () { + /// } + /// + /// false: + /// try { + /// foo(); + /// } catch () { + /// } + /// \endcode bool BeforeCatch; /// \brief Wrap before ``else``. + /// \code + /// true: + /// if (foo()) { + /// } + /// else { + /// } + /// + /// false: + /// if (foo()) { + /// } else { + /// } + /// \endcode bool BeforeElse; /// \brief Indent the wrapped braces themselves. bool IndentBraces; @@ -392,6 +626,17 @@ struct FormatStyle { BraceWrappingFlags BraceWrapping; /// \brief If ``true``, ternary operators will be placed after line breaks. + /// \code + /// true: + /// veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription + /// ? firstValue + /// : SecondValueVeryVeryVeryVeryLong; + /// + /// true: + /// veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription ? + /// firstValue : + /// SecondValueVeryVeryVeryVeryLong; + /// \endcode bool BreakBeforeTernaryOperators; /// \brief Always break constructor initializers before commas and align @@ -424,10 +669,31 @@ struct FormatStyle { /// \brief If ``true``, in the class inheritance expression clang-format will /// break before ``:`` and ``,`` if there is multiple inheritance. + /// \code + /// true: false: + /// class MyClass vs. class MyClass : public X, public Y { + /// : public X }; + /// , public Y { + /// }; + /// \endcode bool BreakBeforeInheritanceComma; /// \brief If the constructor initializers don't fit on a line, put each /// initializer on its own line. + /// \code + /// true: + /// SomeClass::Constructor() + /// : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) { + /// return 0; + /// } + /// + /// false: + /// SomeClass::Constructor() + /// : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa), + /// aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) { + /// return 0; + /// } + /// \endcode bool ConstructorInitializerAllOnOneLineOrOnePerLine; /// \brief The number of characters to use for indentation of constructor _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
