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' ] _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
