[clang-format] Add note directive generation for docs

[gedare]

Summary

Generate a ..note:: directive when the \note is encountered in Format.h

NOTE: Clang-Format Team Automated Review Comment

It looks like your clang-format review does not contain any unit tests, please try to ensure all code changes have a unit test (unless this is an NFC or refactoring, adding documentation etc..)

Add your unit tests in clang/unittests/Format and you can build with ninja FormatTests. We recommend using the verifyFormat(xxx) format of unit tests rather than EXPECT_EQ as this will ensure you change is tolerant to random whitespace changes (see FormatTest.cpp as an example)

For situations where your change is altering the TokenAnnotator.cpp which can happen if you are trying to improve the annotation phase to ensure we are correctly identifying the type of a token, please add a token annotator test in TokenAnnotatorTest.cpp

[gedare]

Update from D153205

[owenpan]

Can you attach a screenshot of how the new note section would look like?

[gedare]

It looks like this:

clang/docs/ClangFormatStyleOptions.rst

* ``BAS_BlockIndent`` (in configuration: ``BlockIndent``)
 
     .. code-block:: c++
 
       someLongFunction(
           argument1, argument2
       )
 
 
-    .. warning::
+    .. note::
 
      This currently only applies to braced initializer lists (when
      ``Cpp11BracedListStyle`` is ``true``) and parentheses.
 
 
 
 .. _AlignArrayOfStructures:
 
 **AlignArrayOfStructures** (``ArrayInitializerAlignmentStyle``) :versionbadge:`clang-format 13` :ref:`¶ <AlignArrayOfStructures>`
   if not ``None``, when using initialization for an array of structs
   aligns the fields into columns.
 
-  NOTE: As of clang-format 15 this option only applied to arrays with equal
+
+  .. note::
+
+   As of clang-format 15 this option only applied to arrays with equal
    number of columns per row.
 
   Possible values:
 
   * ``AIAS_Left`` (in configuration: ``Left``)
     Align array column and left justify the columns e.g.:
 
     .. code-block:: c++
 

 
 
 
 .. _AlignTrailingComments:
 
 **AlignTrailingComments** (``TrailingCommentsAlignmentStyle``) :versionbadge:`clang-format 3.7` :ref:`¶ <AlignTrailingComments>`
   Control of trailing comments.
 
-  NOTE: As of clang-format 16 this option is not a bool but can be set
+
+  .. note::
+
+   As of clang-format 16 this option is not a bool but can be set
    to the options. Conventional bool options still can be parsed as before.
 
 
   .. code-block:: yaml
 
     # Example of usage:
     AlignTrailingComments:
       Kind: Always
       OverEmptyLines: 2
.. code-block:: c++
 
       false:
       namespace {
       int foo();
       int bar();
       }
 
   * ``bool AfterObjCDeclaration`` Wrap ObjC definitions (interfaces, implementations...).
+
+    .. note::
+
      @autoreleasepool and @synchronized blocks are wrapped
      according to `AfterControlStatement` flag.
 
   * ``bool AfterStruct`` Wrap struct definitions.
 
     .. code-block:: c++
 
       true:
       struct foo
       {

 
 .. _BreakArrays:
 
 **BreakArrays** (``Boolean``) :versionbadge:`clang-format 16` :ref:`¶ <BreakArrays>`
   If ``true``, clang-format will always break after a Json array `[`
   otherwise it will scan until the closing `]` to determine if it should add
   newlines between elements (prettier compatible).
 
-  NOTE: This is currently only for formatting JSON.
+
+  .. note::
+
+   This is currently only for formatting JSON.
 
   .. code-block:: c++
 
      true:                                  false:
      [                          vs.      [1, 2, 3, 4]
        1,
        2,
        3,
**ExperimentalAutoDetectBinPacking** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <ExperimentalAutoDetectBinPacking>`
   If ``true``, clang-format detects whether function calls and
   definitions are formatted with one parameter per line.
 
   Each call can be bin-packed, one-per-line or inconclusive. If it is
   inconclusive, e.g. completely on one line, but a decision needs to be
   made, clang-format analyzes whether there are other bin-packed cases in
   the input file and act accordingly.
 
-  NOTE: This is an experimental flag, that might go away or be renamed. Do
+
+  .. note::
+
+   This is an experimental flag, that might go away or be renamed. Do
    not use this in config files, etc. Use at your own risk.
 
 .. _FixNamespaceComments:
 
 **FixNamespaceComments** (``Boolean``) :versionbadge:`clang-format 5` :ref:`¶ <FixNamespaceComments>`
   If ``true``, clang-format adds missing namespace end comments for
   namespaces and fixes invalid existing ones. This doesn't affect short
   namespaces, which are controlled by ``ShortNamespaceLines``.
 
Order is an array that can contain any of the following:
     * inline
     * static
     * friend
     * constexpr
     * volatile
     * restrict
     * type
 
-  Note: it MUST contain 'type'.
+
+  .. note::
+
+   it MUST contain 'type'.
+
   Items to the left of 'type' will be placed to the left of the type and
-  aligned in the order supplied. Items to the right of 'type' will be placed
-  to the right of the type and aligned in the order supplied.
+  aligned in the order supplied. Items to the right of 'type' will be
+  placed to the right of the type and aligned in the order supplied.
 
 
   .. code-block:: yaml
 
     QualifierOrder: ['inline', 'static', 'type', 'const', 'volatile' ]
 
 .. _RawStringFormats:
 

clang/docs/tools/dump_format_style.py

def __clean_comment_line(self, line: str):
 
         match = re.match(r"^/// \\warning$", line)
         if match:
             return "\n.. warning::\n\n"
 
         endwarning_match = re.match(r"^/// +\\endwarning$", line)
         if endwarning_match:
             return ""
+
+        match = re.match(r"^/// \\note$", line)
+        if match:
+            return "\n.. note::\n\n"
+
+        endnote_match = re.match(r"^/// +\\endnote$", line)
+        if endnote_match:
+            return ""
         return line[4:] + "\n"
 
     def read_options(self):
         class State:
             (
                 BeforeStruct,
                 Finished,
                 InStruct,

clang/include/clang/Format/Format.h

enum BracketAlignmentStyle : int8_t {
     /// on a single line. Closing brackets will be placed on a new line.
     /// E.g.:
     /// \code
     ///   someLongFunction(
     ///       argument1, argument2
     ///   )
     /// \endcode
     ///
-    /// \warning
+    /// \note
     ///  This currently only applies to braced initializer lists (when
     ///  ``Cpp11BracedListStyle`` is ``true``) and parentheses.
-    /// \endwarning
+    /// \endnote
     BAS_BlockIndent,
   };
 
   /// If ``true``, horizontally aligns arguments after an open bracket.
   ///
   /// This applies to round brackets (parentheses), angle brackets and square
   /// brackets.
   /// \version 3.8
enum ArrayInitializerAlignmentStyle : int8_t {
     /// \endcode
     AIAS_Right,
     /// Don't align array initializer columns.
     AIAS_None
   };
   /// if not ``None``, when using initialization for an array of structs
   /// aligns the fields into columns.
   ///
-  /// NOTE: As of clang-format 15 this option only applied to arrays with equal
-  /// number of columns per row.
+  /// \note
+  ///  As of clang-format 15 this option only applied to arrays with equal
+  ///  number of columns per row.
+  /// \endnote
   ///
   /// \version 13
   ArrayInitializerAlignmentStyle AlignArrayOfStructures;
 
   /// Alignment options.
   ///
   /// They can also be read as a whole for compatibility. The choices are:
   /// - None
struct TrailingCommentsAlignmentStyle {
     }
     bool operator!=(const TrailingCommentsAlignmentStyle &R) const {
       return !(*this == R);
     }
   };
 
   /// Control of trailing comments.
   ///
-  /// NOTE: As of clang-format 16 this option is not a bool but can be set
-  /// to the options. Conventional bool options still can be parsed as before.
+  /// \note
+  ///  As of clang-format 16 this option is not a bool but can be set
+  ///  to the options. Conventional bool options still can be parsed as before.
+  /// \endnote
   ///
   /// \code{.yaml}
   ///   # Example of usage:
   ///   AlignTrailingComments:
   ///     Kind: Always
   ///     OverEmptyLines: 2
   /// \endcode
   /// \version 3.7
struct BraceWrappingFlags {
     ///   false:
     ///   namespace {
     ///   int foo();
     ///   int bar();
     ///   }
     /// \endcode
     bool AfterNamespace;
     /// Wrap ObjC definitions (interfaces, implementations...).
-    /// \note @autoreleasepool and @synchronized blocks are wrapped
-    /// according to `AfterControlStatement` flag.
+    /// \note
+    ///  @autoreleasepool and @synchronized blocks are wrapped
+    ///  according to `AfterControlStatement` flag.
+    /// \endnote
     bool AfterObjCDeclaration;
     /// Wrap struct definitions.
     /// \code
     ///   true:
     ///   struct foo
     ///   {
     ///     int x;
     ///   };

   /// declaration/definition name.
   /// \version 16
   AttributeBreakingStyle BreakAfterAttributes;
 
   /// If ``true``, clang-format will always break after a Json array `[`
   /// otherwise it will scan until the closing `]` to determine if it should add
   /// newlines between elements (prettier compatible).
   ///
-  /// NOTE: This is currently only for formatting JSON.
+  /// \note
+  ///  This is currently only for formatting JSON.
+  /// \endnote
   /// \code
   ///    true:                                  false:
   ///    [                          vs.      [1, 2, 3, 4]
   ///      1,
   ///      2,
   ///      3,
   ///      4
   ///    ]

   /// If ``true``, clang-format detects whether function calls and
   /// definitions are formatted with one parameter per line.
   ///
   /// Each call can be bin-packed, one-per-line or inconclusive. If it is
   /// inconclusive, e.g. completely on one line, but a decision needs to be
   /// made, clang-format analyzes whether there are other bin-packed cases in
   /// the input file and act accordingly.
   ///
-  /// NOTE: This is an experimental flag, that might go away or be renamed. Do
-  /// not use this in config files, etc. Use at your own risk.
+  /// \note
+  ///  This is an experimental flag, that might go away or be renamed. Do
+  ///  not use this in config files, etc. Use at your own risk.
+  /// \endnote
   /// \version 3.7
   bool ExperimentalAutoDetectBinPacking;
 
   /// If ``true``, clang-format adds missing namespace end comments for
   /// namespaces and fixes invalid existing ones. This doesn't affect short
   /// namespaces, which are controlled by ``ShortNamespaceLines``.
   /// \code
   ///    true:                                  false:

   ///   * inline
   ///   * static
   ///   * friend
   ///   * constexpr
   ///   * volatile
   ///   * restrict
   ///   * type
   ///
-  /// Note: it MUST contain 'type'.
+  /// \note
+  ///  it MUST contain 'type'.
+  /// \endnote
+  ///
   /// Items to the left of 'type' will be placed to the left of the type and
-  /// aligned in the order supplied. Items to the right of 'type' will be placed
-  /// to the right of the type and aligned in the order supplied.
+  /// aligned in the order supplied. Items to the right of 'type' will be
+  /// placed to the right of the type and aligned in the order supplied.
   ///
   /// \code{.yaml}
   ///   QualifierOrder: ['inline', 'static', 'type', 'const', 'volatile' ]
   /// \endcode
   /// \version 14
   std::vector<std::string> QualifierOrder;
 
   /// See documentation of ``RawStringFormats``.