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

[MyDeveloperDay]

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: clang-format: insert trailing commas into containers. D73768: clang-format: [JS] document InsertTrailingCommas. 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)

Generated documentation will look like

[MyDeveloperDay]

clang/docs/ClangFormatStyleOptions.rst

1752

NOTE: options are alphabetic in Format.h and so the position within the rst file will change.

[krasimir]

Awesome! Thank you!
Now that we've got "clang/phabricator/lint/git" robots that leave comments on patches, we may want to think about a way to have this automatically enforced in the future.

[MyDeveloperDay]

In D79095#2010250, @krasimir wrote:

Awesome! Thank you!
Now that we've got "clang/phabricator/lint/git" robots that leave comments on patches, we may want to think about a way to have this automatically enforced in the future.

Thats a great idea.. do you know who looks after those scripts?

[krasimir]

In D79095#2010271, @MyDeveloperDay wrote:

In D79095#2010250, @krasimir wrote:

Awesome! Thank you!
Now that we've got "clang/phabricator/lint/git" robots that leave comments on patches, we may want to think about a way to have this automatically enforced in the future.

Thats a great idea.. do you know who looks after those scripts?

I asked around and a simple thing we can do that would have the effect of complaining on the Phabricator patch if the format options doc has to be regenerated is a lit test that does a diff.
Will prepare a patch, after this lands, so that the newly added test doesn't fail at first.

clang/docs/ClangFormatStyleOptions.rst

.. code-block:: c++
 
     false:
     void f() {
       f(aaaaaaaaaaaaaaaaaaaa,
         aaaaaaaaaaaaaaaaaaaa,
         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.
 
   .. code-block:: c++
 
     true:
     void f(int aaaaaaaaaaaaaaaaaaaa, int aaaaaaaaaaaaaaaaaaaa,
.. code-block:: c++
 
      true:
      LoooooooooooooooooooooooooooooooooooooooongReturnType
          LoooooooooooooooooooooooooooooooongFunctionDeclaration();
 
      false:
      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.
 
   Each group is separated by a newline. Static imports will also follow the
   same grouping convention above all non-static imports. One group's prefix
   can be a subset of another - the longest prefix is always matched. Within
   a group, the imports are ordered lexicographically.
 
**ObjCBreakBeforeNestedBlockParam** (``bool``)
   Break parameters list into lines when there is nested block
   parameters in a fuction call.
 
   .. code-block:: c++
 
     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;
          }]
      }
      true:
      - (void)_aMethod
      {
         [self.test1 t:self
                      w:self
-             callback:^(typeof(self) self, NSNumber *u, NSNumber *v) {
                  u = c;
              }]
      }
 
 **ObjCSpaceAfterProperty** (``bool``)
   Add a space after ``@property`` in Objective-C, i.e. use
   ``@property (readonly)`` instead of ``@property(readonly)``.
 
**UseTab** (``UseTabStyle``)
   * ``UT_ForIndentation`` (in configuration: ``ForIndentation``)
     Use tabs only for indentation.
 
   * ``UT_ForContinuationAndIndentation`` (in configuration: ``ForContinuationAndIndentation``)
     Fill all leading whitespace with tabs, and use spaces for alignment that
     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
     one tab stop to the next one.
 
 
 
 .. END_FORMAT_STYLE_OPTIONS

clang/include/clang/Format/Format.h

enum TrailingCommaStyle {
     /// 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.
     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
   /// parameters will either all be on the same line or will have one line each.
   /// \code
   ///   true:
   ///   void f(int aaaaaaaaaaaaaaaaaaaa, int aaaaaaaaaaaaaaaaaaaa,
   ///          int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
enum UseTabStyle {
     /// Never use tab.
     UT_Never,
     /// Use tabs only for indentation.
     UT_ForIndentation,
     /// Fill all leading whitespace with tabs, and use spaces for alignment that
     /// 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.
     UT_Always
   };
 
   /// \brief Use ``\r\n`` instead of ``\n`` for line breaks.
   /// Also used as fallback if ``DeriveLineEnding`` is true.