From: Sylvestre Ledru Date: Wed, 8 Mar 2017 13:24:46 +0000 (+0000) Subject: Add more examples to clang-format configuration X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=daad58b44fcc39de10e1a38a4a4e6aaa3c8ed01a;p=clang Add more examples to clang-format configuration Reviewers: djasper Reviewed By: djasper Subscribers: cfe-commits, klimek Differential Revision: https://reviews.llvm.org/D30734 git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@297275 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/docs/ClangFormatStyleOptions.rst b/docs/ClangFormatStyleOptions.rst index 0d3f1ad60a..98211c421b 100644 --- a/docs/ClangFormatStyleOptions.rst +++ b/docs/ClangFormatStyleOptions.rst @@ -283,12 +283,32 @@ the configuration (without a prefix: ``Auto``). * ``SFS_Empty`` (in configuration: ``Empty``) Only merge empty functions. + .. code-block:: c++ + + void f() { bar(); } + void f2() { + bar2(); + } + * ``SFS_Inline`` (in configuration: ``Inline``) Only merge functions defined inside a class. Implies "empty". + .. code-block:: c++ + + class { + void f() { foo(); } + }; + * ``SFS_All`` (in configuration: ``All``) Merge all functions fitting on a single line. + .. code-block:: c++ + + class { + void f() { foo(); } + }; + void f() { bar(); } + **AllowShortIfStatementsOnASingleLine** (``bool``) @@ -325,18 +345,78 @@ the configuration (without a prefix: ``Auto``). Break after return type automatically. ``PenaltyReturnTypeOnItsOwnLine`` is taken into account. + .. code-block:: c++ + + class A { + int f() { return 0; }; + }; + int f(); + int f() { return 1; } + * ``RTBS_All`` (in configuration: ``All``) Always break after the return type. + .. code-block:: c++ + + class A { + int + f() { + return 0; + }; + }; + int + f(); + int + f() { + return 1; + } + * ``RTBS_TopLevel`` (in configuration: ``TopLevel``) Always break after the return types of top-level functions. + .. code-block:: c++ + + class A { + int f() { return 0; }; + }; + int + f(); + int + f() { + return 1; + } + * ``RTBS_AllDefinitions`` (in configuration: ``AllDefinitions``) Always break after the return type of function definitions. + .. code-block:: c++ + + class A { + int + f() { + return 0; + }; + }; + int f(); + int + f() { + return 1; + } + * ``RTBS_TopLevelDefinitions`` (in configuration: ``TopLevelDefinitions``) Always break after the return type of top-level definitions. + .. code-block:: c++ + + class A { + int f() { return 0; }; + }; + int f(); + int + f() { + return 1; + } + **AlwaysBreakBeforeMultilineStrings** (``bool``) @@ -722,12 +802,24 @@ the configuration (without a prefix: ``Auto``). * ``PAS_Left`` (in configuration: ``Left``) Align pointer to the left. + .. code-block:: c++ + + int\* a; + * ``PAS_Right`` (in configuration: ``Right``) Align pointer to the right. + .. code-block:: c++ + + int \*a; + * ``PAS_Middle`` (in configuration: ``Middle``) Align pointer in the middle. + .. code-block:: c++ + + int \* a; + **ReflowComments** (``bool``) @@ -736,8 +828,19 @@ the configuration (without a prefix: ``Auto``). **SortIncludes** (``bool``) If ``true``, clang-format will sort ``#includes``. + .. code-block:: c++ + + false: true: + #include "b.h" vs. #include "a.h" + #include "a.h" #include "b.h" + **SpaceAfterCStyleCast** (``bool``) - If ``true``, a space may be inserted after C style casts. + If ``true``, a space is inserted after C style casts. + + .. code-block:: c++ + + true: false: + (int)i; vs. (int) i; **SpaceAfterTemplateKeyword** (``bool``) If ``true``, a space will be inserted after the 'template' keyword. diff --git a/include/clang/Format/Format.h b/include/clang/Format/Format.h index 33c155c367..d017247b7b 100644 --- a/include/clang/Format/Format.h +++ b/include/clang/Format/Format.h @@ -162,10 +162,27 @@ struct FormatStyle { /// \brief Never merge functions into a single line. SFS_None, /// \brief Only merge empty functions. + /// \code + /// void f() { bar(); } + /// void f2() { + /// bar2(); + /// } + /// \endcode SFS_Empty, /// \brief Only merge functions defined inside a class. Implies "empty". + /// \code + /// class { + /// void f() { foo(); } + /// }; + /// \endcode SFS_Inline, /// \brief Merge all functions fitting on a single line. + /// \code + /// class { + /// void f() { foo(); } + /// }; + /// void f() { bar(); } + /// \endcode SFS_All, }; @@ -181,6 +198,7 @@ struct FormatStyle { bool AllowShortLoopsOnASingleLine; /// \brief Different ways to break after the function definition return type. + /// This option is deprecated and is retained for backwards compatibility. enum DefinitionReturnTypeBreakingStyle { /// Break after return type automatically. /// ``PenaltyReturnTypeOnItsOwnLine`` is taken into account. @@ -196,14 +214,69 @@ struct FormatStyle { enum ReturnTypeBreakingStyle { /// Break after return type automatically. /// ``PenaltyReturnTypeOnItsOwnLine`` is taken into account. + /// \code + /// class A { + /// int f() { return 0; }; + /// }; + /// int f(); + /// int f() { return 1; } + /// \endcode RTBS_None, /// Always break after the return type. + /// \code + /// class A { + /// int + /// f() { + /// return 0; + /// }; + /// }; + /// int + /// f(); + /// int + /// f() { + /// return 1; + /// } + /// \endcode RTBS_All, /// Always break after the return types of top-level functions. + /// \code + /// class A { + /// int f() { return 0; }; + /// }; + /// int + /// f(); + /// int + /// f() { + /// return 1; + /// } + /// \endcode RTBS_TopLevel, /// Always break after the return type of function definitions. + /// \code + /// class A { + /// int + /// f() { + /// return 0; + /// }; + /// }; + /// int f(); + /// int + /// f() { + /// return 1; + /// } + /// \endcode RTBS_AllDefinitions, /// Always break after the return type of top-level definitions. + /// \code + /// class A { + /// int f() { return 0; }; + /// }; + /// int f(); + /// int + /// f() { + /// return 1; + /// } + /// \endcode RTBS_TopLevelDefinitions, }; @@ -589,10 +662,19 @@ struct FormatStyle { /// \brief The ``&`` and ``*`` alignment style. enum PointerAlignmentStyle { /// Align pointer to the left. + /// \code + /// int* a; + /// \endcode PAS_Left, /// Align pointer to the right. + /// \code + /// int *a; + /// \endcode PAS_Right, /// Align pointer in the middle. + /// \code + /// int * a; + /// \endcode PAS_Middle }; @@ -603,9 +685,18 @@ struct FormatStyle { bool ReflowComments; /// \brief If ``true``, clang-format will sort ``#includes``. + /// \code + /// false: true: + /// #include "b.h" vs. #include "a.h" + /// #include "a.h" #include "b.h" + /// \endcode bool SortIncludes; - /// \brief If ``true``, a space may be inserted after C style casts. + /// \brief If ``true``, a space is inserted after C style casts. + /// \code + /// true: false: + /// (int)i; vs. (int) i; + /// \endcode bool SpaceAfterCStyleCast; /// \brief If \c true, a space will be inserted after the 'template' keyword.