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:`¶ <MacroBlockEnd>`
   A regular expression matching macros that end a block.
 
+.. _Macros:
+
+**Macros** (``List of Strings``) :versionbadge:`clang-format 17.0` :ref:`¶ <Macros>`
+  A list of macros of the form ``<definition>=<expansion>`` .
+
+  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:`¶ <MaxEmptyLinesToKeep>`
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<std::string> Macros;
 
   /// The maximum number of consecutive empty lines to keep.