[clang] 0fa7e4a - [clang-format] NFC Correct clang-format headers file so documentation can be once again autogenerated

[via cfe-commits]

Author: mydeveloperday
Date: 2020-04-30T10:50:29+01:00
New Revision: 0fa7e4adcafb35126f87fb3a45f6f668c994c3e7

URL: https://github.com/llvm/llvm-project/commit/0fa7e4adcafb35126f87fb3a45f6f668c994c3e7
DIFF: https://github.com/llvm/llvm-project/commit/0fa7e4adcafb35126f87fb3a45f6f668c994c3e7.diff

LOG: [clang-format] NFC Correct clang-format headers file so documentation can be once again autogenerated

Summary:
`ClangFormatStyleOptions.rst` should ALWAYS be autogenerated from Format.h using `clang/docs/tools/dump_format_style.py` if not its liable to get removed leaving options undocumented.

This revision reworks the documentation for {D73354} {D73768} to ensure we can continue to regenerated

Fix other minor changes that ensure the documentation remains consistent (Format.h obviously got re clang-formatted after the rst had been regenerated previously)

Reviewed By: krasimir

Subscribers: cfe-commits

Tags: #clang, #clang-format

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

Added: 
    

Modified: 
    clang/docs/ClangFormatStyleOptions.rst
    clang/include/clang/Format/Format.h

Removed: 
    


################################################################################
diff  --git a/clang/docs/ClangFormatStyleOptions.rst b/clang/docs/ClangFormatStyleOptions.rst
index 6d486224e3c2..01ab0db490e4 100644
--- a/clang/docs/ClangFormatStyleOptions.rst
+++ b/clang/docs/ClangFormatStyleOptions.rst
@@ -717,26 +717,6 @@ the configuration (without a prefix: ``Auto``).
         aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
     }
 
-
-**InsertTrailingCommas** (``TrailingCommaStyle``) can be set to ``TCS_Wrapped``
-  to insert trailing commas in container literals (arrays and objects) that wrap
-  across multiple lines. It is currently only available for JavaScript and
-  disabled by default (``TCS_None``).
-
-  ``InsertTrailingCommas`` cannot be used together with ``BinPackArguments`` as
-  inserting the comma disables bin-packing.
-
-  .. code-block:: c++
-
-    TSC_Wrapped:
-    const someArray = [
-      aaaaaaaaaaaaaaaaaaaaaaaaaa,
-      aaaaaaaaaaaaaaaaaaaaaaaaaa,
-      aaaaaaaaaaaaaaaaaaaaaaaaaa,
-      //                        ^ inserted
-    ]
-
-
 **BinPackParameters** (``bool``)
   If ``false``, a function declaration's or function definition's
   parameters will either all be on the same line or will have one line each.
@@ -1770,6 +1750,38 @@ the configuration (without a prefix: ``Auto``).
      LoooooooooooooooooooooooooooooooooooooooongReturnType
      LoooooooooooooooooooooooooooooooongFunctionDeclaration();
 
+**InsertTrailingCommas** (``TrailingCommaStyle``)
+  If set to ``TCS_Wrapped`` will insert trailing commas in container
+  literals (arrays and objects) that wrap across multiple lines.
+  It is currently only available for JavaScript
+  and disabled by default ``TCS_None``.
+  ``InsertTrailingCommas`` cannot be used together with ``BinPackArguments``
+  as inserting the comma disables bin-packing.
+
+  .. code-block:: c++
+
+    TSC_Wrapped:
+    const someArray = [
+    aaaaaaaaaaaaaaaaaaaaaaaaaa,
+    aaaaaaaaaaaaaaaaaaaaaaaaaa,
+    aaaaaaaaaaaaaaaaaaaaaaaaaa,
+    //                        ^ inserted
+    ]
+
+  Possible values:
+
+  * ``TCS_None`` (in configuration: ``None``)
+    Do not insert trailing commas.
+
+  * ``TCS_Wrapped`` (in configuration: ``Wrapped``)
+    Insert trailing commas in container literals that were wrapped over
+    multiple lines. Note that this is conceptually incompatible with
+    bin-packing, because the trailing comma is used as an indicator
+    that a container should be formatted one-per-line (i.e. not bin-packed).
+    So inserting a trailing comma counteracts bin-packing.
+
+
+
 **JavaImportGroups** (``std::vector<std::string>``)
   A vector of prefixes ordered by the desired groups for Java imports.
 
@@ -2064,7 +2076,8 @@ the configuration (without a prefix: ``Auto``).
     false:
      - (void)_aMethod
      {
-         [self.test1 t:self w:self callback:^(typeof(self) self, NSNumber *u, NSNumber *v) {
+         [self.test1 t:self w:self callback:^(typeof(self) self, NSNumber
+         *u, NSNumber *v) {
              u = c;
          }]
      }
@@ -2072,8 +2085,8 @@ the configuration (without a prefix: ``Auto``).
      - (void)_aMethod
      {
         [self.test1 t:self
-                    w:self
-             callback:^(typeof(self) self, NSNumber *u, NSNumber *v) {
+                     w:self
+            callback:^(typeof(self) self, NSNumber *u, NSNumber *v) {
                  u = c;
              }]
      }
@@ -2538,7 +2551,8 @@ the configuration (without a prefix: ``Auto``).
     appears within a line (e.g. consecutive assignments and declarations).
 
   * ``UT_AlignWithSpaces`` (in configuration: ``AlignWithSpaces``)
-    Use tabs for line continuation and indentation, and spaces for alignment.
+    Use tabs for line continuation and indentation, and spaces for
+    alignment.
 
   * ``UT_Always`` (in configuration: ``Always``)
     Use tabs whenever we need to fill whitespace that spans at least from

diff  --git a/clang/include/clang/Format/Format.h b/clang/include/clang/Format/Format.h
index 2b2edc4adc11..1143b1815050 100644
--- a/clang/include/clang/Format/Format.h
+++ b/clang/include/clang/Format/Format.h
@@ -561,6 +561,21 @@ struct FormatStyle {
     TCS_Wrapped,
   };
 
+  /// If set to ``TCS_Wrapped`` will insert trailing commas in container
+  /// literals (arrays and objects) that wrap across multiple lines.
+  /// It is currently only available for JavaScript
+  /// and disabled by default ``TCS_None``.
+  /// ``InsertTrailingCommas`` cannot be used together with ``BinPackArguments``
+  /// as inserting the comma disables bin-packing.
+  /// \code
+  ///   TSC_Wrapped:
+  ///   const someArray = [
+  ///   aaaaaaaaaaaaaaaaaaaaaaaaaa,
+  ///   aaaaaaaaaaaaaaaaaaaaaaaaaa,
+  ///   aaaaaaaaaaaaaaaaaaaaaaaaaa,
+  ///   //                        ^ inserted
+  ///   ]
+  /// \endcode
   TrailingCommaStyle InsertTrailingCommas;
 
   /// If ``false``, a function declaration's or function definition's
@@ -2133,7 +2148,7 @@ struct FormatStyle {
     /// appears within a line (e.g. consecutive assignments and declarations).
     UT_ForContinuationAndIndentation,
     /// Use tabs for line continuation and indentation, and spaces for
-    /// alignemnt.
+    /// alignment.
     UT_AlignWithSpaces,
     /// Use tabs whenever we need to fill whitespace that spans at least from
     /// one tab stop to the next one.