[PATCH] D154552: [clang-format] Add note directive generation for docs

[Owen Pan via Phabricator via cfe-commits]

This revision was landed with ongoing or failed builds.
This revision was automatically updated to reflect the committed changes.
Closed by commit rG9ec5dc694478: [clang-format] Add note directive generation 
for docs (authored by gedare, committed by owenpan).

Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154552/new/

https://reviews.llvm.org/D154552

Files:
  clang/docs/ClangFormatStyleOptions.rst
  clang/docs/tools/dump_format_style.py
  clang/include/clang/Format/Format.h

Index: clang/include/clang/Format/Format.h
===
--- clang/include/clang/Format/Format.h
+++ clang/include/clang/Format/Format.h
@@ -92,10 +92,10 @@
 ///   )
 /// \endcode
 ///
-/// \warning
+/// \note
 ///  This currently only applies to braced initializer lists (when
 ///  ``Cpp11BracedListStyle`` is ``true``) and parentheses.
-/// \endwarning
+/// \endnote
 BAS_BlockIndent,
   };
 
@@ -134,8 +134,10 @@
   /// 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;
@@ -440,8 +442,10 @@
 
   /// 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:
@@ -1094,8 +1098,10 @@
 /// \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
@@ -1290,7 +1296,9 @@
   /// 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]
@@ -2180,8 +2188,10 @@
   /// 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;
 
@@ -3200,10 +3210,13 @@
   ///   * 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' ]
Index: clang/docs/tools/dump_format_style.py
===
--- clang/docs/tools/dump_format_style.py
+++ clang/docs/tools/dump_format_style.py
@@ -257,6 +257,14 @@
 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):
Index: clang/docs/ClangFormatStyleOptions.rst
===
--- clang/docs/ClangFormatStyleOptions.rst
+++ clang/docs/ClangFormatStyleOptions.rst
@@ -239,7 +239,7 @@
   )
 
 
-.. warning::
+.. note::
 
  This currently only applies to braced 

[PATCH] D154552: [clang-format] Add note directive generation for docs

[Gedare Bloom via Phabricator via cfe-commits]

gedare added a comment.

It looks like this:
F28163425: image.png 


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154552/new/

https://reviews.llvm.org/D154552

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154552: [clang-format] Add note directive generation for docs

[Owen Pan via Phabricator via cfe-commits]

owenpan added a comment.

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


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154552/new/

https://reviews.llvm.org/D154552

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D154552: [clang-format] Add note directive generation for docs

[Gedare Bloom via Phabricator via cfe-commits]

gedare updated this revision to Diff 537872.
gedare added a comment.

Update from D153205 


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D154552/new/

https://reviews.llvm.org/D154552

Files:
  clang/docs/ClangFormatStyleOptions.rst
  clang/docs/tools/dump_format_style.py
  clang/include/clang/Format/Format.h

Index: clang/include/clang/Format/Format.h
===
--- clang/include/clang/Format/Format.h
+++ clang/include/clang/Format/Format.h
@@ -92,10 +92,10 @@
 ///   )
 /// \endcode
 ///
-/// \warning
+/// \note
 ///  This currently only applies to braced initializer lists (when
 ///  ``Cpp11BracedListStyle`` is ``true``) and parentheses.
-/// \endwarning
+/// \endnote
 BAS_BlockIndent,
   };
 
@@ -134,8 +134,10 @@
   /// 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;
@@ -440,8 +442,10 @@
 
   /// 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:
@@ -1094,8 +1098,10 @@
 /// \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
@@ -1290,7 +1296,9 @@
   /// 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]
@@ -2180,8 +2188,10 @@
   /// 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;
 
@@ -3200,10 +3210,13 @@
   ///   * 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' ]
Index: clang/docs/tools/dump_format_style.py
===
--- clang/docs/tools/dump_format_style.py
+++ clang/docs/tools/dump_format_style.py
@@ -257,6 +257,14 @@
 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):
Index: clang/docs/ClangFormatStyleOptions.rst
===
--- clang/docs/ClangFormatStyleOptions.rst
+++ clang/docs/ClangFormatStyleOptions.rst
@@ -239,7 +239,7 @@
   )
 
 
-.. warning::
+.. note::
 
  This currently only applies to braced initializer lists (when
  ``Cpp11BracedListStyle`` is ``true``) and parentheses.
@@ -252,8 +252,11 @@
   if not ``None``, when using 

[PATCH] D154552: [clang-format] Add note directive generation for docs

[Gedare Bloom via Phabricator via cfe-commits]

gedare created this revision.
Herald added projects: All, clang, clang-format.
Herald added a subscriber: cfe-commits.
Herald added reviewers: rymiel, HazardyKnusperkeks, owenpan, MyDeveloperDay.
gedare requested review of this revision.
Herald added a comment.

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`


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


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D154552

Files:
  clang/docs/ClangFormatStyleOptions.rst
  clang/docs/tools/dump_format_style.py
  clang/include/clang/Format/Format.h

Index: clang/include/clang/Format/Format.h
===
--- clang/include/clang/Format/Format.h
+++ clang/include/clang/Format/Format.h
@@ -133,8 +133,10 @@
   /// 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;
@@ -439,8 +441,10 @@
 
   /// 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:
@@ -1093,8 +1097,10 @@
 /// \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
@@ -1289,7 +1295,9 @@
   /// 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]
@@ -2179,8 +2187,10 @@
   /// 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;
 
@@ -3199,10 +3209,12 @@
   ///   * restrict
   ///   * 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.
+  /// \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.
+  /// \endnote
   ///
   /// \code{.yaml}
   ///   QualifierOrder: ['inline', 'static', 'type', 'const', 'volatile' ]
Index: clang/docs/tools/dump_format_style.py
===
--- clang/docs/tools/dump_format_style.py
+++ clang/docs/tools/dump_format_style.py
@@ -257,6 +257,14 @@
 endwarning_match = re.match(r"^/// +\\endwarning$", line)
 if endwarning_match:
 return ""
+
+match =