Index: clang/docs/ClangFormatStyleOptions.rst =================================================================== --- clang/docs/ClangFormatStyleOptions.rst +++ clang/docs/ClangFormatStyleOptions.rst @@ -3642,6 +3642,49 @@ **MacroBlockEnd** (``String``) :versionbadge:`clang-format 3.7` :ref:`¶ ` A regular expression matching macros that end a block. +.. _Macros: + +**Macros** (``List of Strings``) :versionbadge:`clang-format 17.0` :ref:`¶ ` + A list of macros of the form ``=`` . + + Code will be parsed with macros expanded, in order to determine how to + interpret and format the macro arguments. + + For example, the code: + + .. code-block:: c++ + + A(a*b); + + will usually be interpreted as a call to a function A, and the + multiplication expression will be formatted as `a * b`. + + If we specify the macro definition: + + .. code-block:: yaml + + Macros: + - A(x)=x + + the code will now be parsed as a declaration of the variable b of type a*, + and formatted as `a* b` (depending on pointer-binding rules). + + Features and restrictions: + * Both function-like macros and object-like macros are supported. + * Macro arguments must be used exactly once in the expansion. + * No recursive expansion; macros referencing other macros will be + ignored. + * Overloading by arity is supported: for example, given the macro + definitions A=x, A()=y, A(a)=a + + + .. code-block:: c++ + + A; -> x; + A(); -> y; + A(z); -> z; + A(a, b); // will not be expanded. + .. _MaxEmptyLinesToKeep: **MaxEmptyLinesToKeep** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ ` Index: clang/include/clang/Format/Format.h =================================================================== --- clang/include/clang/Format/Format.h +++ clang/include/clang/Format/Format.h @@ -2754,28 +2754,35 @@ /// \code /// A(a*b); /// \endcode + /// /// will usually be interpreted as a call to a function A, and the /// multiplication expression will be formatted as `a * b`. /// /// If we specify the macro definition: - /// \code + /// \code{.yaml} /// Macros: /// - A(x)=x /// \endcode + /// /// the code will now be parsed as a declaration of the variable b of type a*, /// and formatted as `a* b` (depending on pointer-binding rules). /// /// Features and restrictions: - /// * Both function-like macros and object-like macros are supported. - /// * Macro arguments must be used exactly once in the expansion. - /// * No recursive expansion; macros referencing other macros will be + /// * Both function-like macros and object-like macros are supported. + /// * Macro arguments must be used exactly once in the expansion. + /// * No recursive expansion; macros referencing other macros will be /// ignored. - /// * Overloading by arity is supported: for example, given the macro - /// definitions A=x, A()=y, A(a)=a, - /// 'A;' -> 'x;' - /// 'A();' -> 'y;' - /// 'A(z);' -> 'z;' - /// 'A(a, b) will not be expanded. + /// * Overloading by arity is supported: for example, given the macro + /// definitions A=x, A()=y, A(a)=a + /// + /// \code + /// A; -> x; + /// A(); -> y; + /// A(z); -> z; + /// A(a, b); // will not be expanded. + /// \endcode + /// + /// \version 17.0 std::vector Macros; /// The maximum number of consecutive empty lines to keep.