[clang-format] NFC Format.h and ClangFormatStyleOptions.rst are out of date

Regenerate the style documentation, requires some minor sphinx changes to avoid warnings

Reviewed By: klimek

Differential Revision: https://reviews.llvm.org/D146704

diff --git a/clang/docs/ClangFormatStyleOptions.rst b/clang/docs/ClangFormatStyleOptions.rst
index fd8f2bb..24ae02a 100644 (file)
--- a/clang/docs/ClangFormatStyleOptions.rst
+++ b/clang/docs/ClangFormatStyleOptions.rst
@@ -3642,6 +3642,49 @@ the configuration (without a prefix: ``Auto``).
 **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>`

diff --git a/clang/include/clang/Format/Format.h b/clang/include/clang/Format/Format.h
index 66904a6..a55cd76 100644 (file)
--- a/clang/include/clang/Format/Format.h
+++ b/clang/include/clang/Format/Format.h
@@ -2754,28 +2754,35 @@ struct FormatStyle {
   /// \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.