[clang] 9ec5dc6 - [clang-format] Add note directive generation for docs
Owen Pan via cfe-commits
cfe-commits at lists.llvm.org
Sun Jul 9 12:25:11 PDT 2023
Author: Gedare Bloom
Date: 2023-07-09T12:24:55-07:00
New Revision: 9ec5dc6944781b0c233e874a4ed8d12106df14ac
URL: https://github.com/llvm/llvm-project/commit/9ec5dc6944781b0c233e874a4ed8d12106df14ac
DIFF: https://github.com/llvm/llvm-project/commit/9ec5dc6944781b0c233e874a4ed8d12106df14ac.diff
LOG: [clang-format] Add note directive generation for docs
Generate a ..note:: directive when the \note is encountered in Format.h.
Differential Revision: https://reviews.llvm.org/D154552
Added:
Modified:
clang/docs/ClangFormatStyleOptions.rst
clang/docs/tools/dump_format_style.py
clang/include/clang/Format/Format.h
Removed:
################################################################################
diff --git a/clang/docs/ClangFormatStyleOptions.rst b/clang/docs/ClangFormatStyleOptions.rst
index 3dbb955347da2d..866bf0910898b3 100644
--- a/clang/docs/ClangFormatStyleOptions.rst
+++ b/clang/docs/ClangFormatStyleOptions.rst
@@ -239,7 +239,7 @@ the configuration (without a prefix: ``Auto``).
)
- .. warning::
+ .. note::
This currently only applies to braced initializer lists (when
``Cpp11BracedListStyle`` is ``true``) and parentheses.
@@ -252,8 +252,11 @@ the configuration (without a prefix: ``Auto``).
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.
Possible values:
@@ -879,8 +882,11 @@ the configuration (without a prefix: ``Auto``).
**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
- 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.
.. code-block:: yaml
@@ -1677,8 +1683,11 @@ the configuration (without a prefix: ``Auto``).
}
* ``bool AfterObjCDeclaration`` Wrap ObjC definitions (interfaces, implementations...).
- @autoreleasepool and @synchronized blocks are wrapped
- according to `AfterControlStatement` flag.
+
+ .. note::
+
+ @autoreleasepool and @synchronized blocks are wrapped
+ according to `AfterControlStatement` flag.
* ``bool AfterStruct`` Wrap struct definitions.
@@ -1921,7 +1930,10 @@ the configuration (without a prefix: ``Auto``).
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++
@@ -2877,8 +2889,11 @@ the configuration (without a prefix: ``Auto``).
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.
.. _FixNamespaceComments:
@@ -4177,10 +4192,14 @@ the configuration (without a prefix: ``Auto``).
* 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
diff --git a/clang/docs/tools/dump_format_style.py b/clang/docs/tools/dump_format_style.py
index 0b7399aee9fd5e..270ac34c03b39c 100755
--- a/clang/docs/tools/dump_format_style.py
+++ b/clang/docs/tools/dump_format_style.py
@@ -257,6 +257,14 @@ def __clean_comment_line(self, line: str):
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):
diff --git a/clang/include/clang/Format/Format.h b/clang/include/clang/Format/Format.h
index ca4e89dcafc9d4..3992dd89fb950d 100644
--- a/clang/include/clang/Format/Format.h
+++ b/clang/include/clang/Format/Format.h
@@ -92,10 +92,10 @@ struct FormatStyle {
/// )
/// \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 @@ struct FormatStyle {
/// 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 @@ struct FormatStyle {
/// 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 @@ struct FormatStyle {
/// \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 @@ struct FormatStyle {
/// 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 @@ struct FormatStyle {
/// 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 @@ struct FormatStyle {
/// * 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' ]
More information about the cfe-commits
mailing list