[clang-format] Extract doc for entire configuration structs

[sstwcw]

Summary

Previously the comments for configuration structs as a whole like
BraceWrappingFlags did not go into the doc.

[HazardyKnusperkeks]

Seems to be correct, but I have not enough knowledge about the python or rst stuff.

[curdeius]

LGTM!

clang/docs/ClangFormatStyleOptions.rst

.. code-block:: yaml
     BreakBeforeBraces: Custom
     BraceWrapping:
       AfterEnum: true
       AfterStruct: false
       SplitEmptyFunction: false
 
   Nested configuration flags:
 
+  Precise control over the wrapping of braces.
+
+  .. code-block:: c++
+
+    # Should be declared this way:
+    BreakBeforeBraces: Custom
+    BraceWrapping:
+        AfterClass: true
 
   * ``bool AfterCaseLabel`` Wrap case labels.
 
     .. code-block:: c++
 
       false:                                true:
       switch (foo) {                vs.     switch (foo) {
         case 1: {                             case 1:
.. code-block:: yaml
     # Example of usage:
     SpaceBeforeParens: Custom
     SpaceBeforeParensOptions:
       AfterControlStatements: true
       AfterFunctionDefinitionName: true
 
   Nested configuration flags:
 
+  Precise control over the spacing before parentheses.
+
+  .. code-block:: c++
+
+    # Should be declared this way:
+    SpaceBeforeParens: Custom
+    SpaceBeforeParensOptions:
+      AfterControlStatements: true
+      AfterFunctionDefinitionName: true
 
   * ``bool AfterControlStatements`` If ``true``, put space betwee control statement keywords
     (for/if/while...) and opening parentheses.
 
     .. code-block:: c++
 
        true:                                  false:
        if (...) {}                     vs.    if(...) {}
.. code-block:: c++
 
     Maximum: 0
     /// List:                                 ///List:
     ///  - Foo                                /// - Foo
     ///    - Bar                              ///   - Bar
 
   Nested configuration flags:
 
+  Control of spaces within a single line comment
 
   * ``unsigned Minimum`` The minimum number of spaces at the start of the comment.
 
   * ``unsigned Maximum`` The maximum number of spaces at the start of the comment.
 
 
 **SpacesInParentheses** (``Boolean``) :versionbadge:`clang-format 3.7`
   If ``true``, spaces will be inserted after ``(`` and before ``)``.

clang/docs/tools/dump_format_style.py

 
 class NestedStruct(object):
   def __init__(self, name, comment):
     self.name = name
     self.comment = comment.strip()
     self.values = []
 
   def __str__(self):
-    return '\n'.join(map(str, self.values))
+    return self.comment + '\n' + '\n'.join(map(str, self.values))
 
 class NestedField(object):
   def __init__(self, name, comment):
     self.name = name
     self.comment = comment.strip()
 
   def __str__(self):
     return '\n* ``%s`` %s' % (