clang-format: Update flag documentation, and generation script.

llvm-svn: 205853

clang/docs/ClangFormatStyleOptions.rst

@@ -106,9 +106,19 @@ the configuration (without a prefix: ``Auto``).
   Allow putting all parameters of a function declaration onto
   the next line even if ``BinPackParameters`` is ``false``.
 
-**AllowShortFunctionsOnASingleLine** (``bool``)
-  If ``true``, ``int f() { return 0; }`` can be put on a single
-  line.
+**AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``)
+  Dependent on the value, ``int f() { return 0; }`` can be put
+  on a single line.
+
+  Possible values:
+
+  * ``SFS_None`` (in configuration: ``None``)
+    Never merge functions into a single line.
+  * ``SFS_Inline`` (in configuration: ``Inline``)
+    Only merge functions defined inside a class.
+  * ``SFS_All`` (in configuration: ``All``)
+    Merge all functions fitting on a single line.
+
 
 **AllowShortIfStatementsOnASingleLine** (``bool``)
   If ``true``, ``if (a) return;`` can be put on a single
@@ -213,12 +223,16 @@ the configuration (without a prefix: ``Auto``).
   not use this in config files, etc. Use at your own risk.
 
 **ForEachMacros** (``std::vector<std::string>``)
-  A list of macros that should be interpreted as foreach loops instead of as
-  function calls.
+  A vector of macros that should be interpreted as foreach loops
+  instead of as function calls.
 
-  For example, ``ForEachMacros: [BOOST_FOREACH, Q_FOREACH]`` tells
-  clang-format to treat ``BOOST_FOREACH`` and ``Q_FOREACH`` as loop control
-  statements.
+  These are expected to be macros of the form:
+  \code
+  FOREACH(<variable-declaration>, ...)
+  <loop-body>
+  \endcode
+
+  For example: BOOST_FOREACH.
 
 **IndentCaseLabels** (``bool``)
   Indent case labels one level from the switch statement.
@@ -233,6 +247,9 @@ the configuration (without a prefix: ``Auto``).
 **IndentWidth** (``unsigned``)
   The number of columns to use for indentation.
 
+**KeepEmptyLinesAtTheStartOfBlocks** (``bool``)
+  If true, empty lines at the start of blocks are kept.
+
 **Language** (``LanguageKind``)
   Language, this format style is targeted at.
 
@@ -319,7 +336,10 @@ the configuration (without a prefix: ``Auto``).
   If ``true``, spaces may be inserted into '()'.
 
 **SpacesBeforeTrailingComments** (``unsigned``)
-  The number of spaces to before trailing line comments.
+  The number of spaces before trailing line comments (//-comments).
+
+  This does not affect trailing block comments (/**/-comments) as those
+  commonly have different usage patterns and a number of special cases.
 
 **SpacesInAngles** (``bool``)
   If ``true``, spaces will be inserted after '<' and before '>' in

clang/docs/tools/dump_format_style.py

@@ -98,7 +98,7 @@ def read_options(header):
         enum = Enum(name, comment)
       elif line.endswith(';'):
         state = State.InStruct
-        field_type, field_name = re.match(r'([:\w]+)\s+(\w+);', line).groups()
+        field_type, field_name = re.match(r'([<>:\w]+)\s+(\w+);', line).groups()
         option = Option(str(field_name), str(field_type), comment)
         options.append(option)
       else:
@@ -122,7 +122,8 @@ def read_options(header):
     raise Exception('Not finished by the end of file')
 
   for option in options:
-    if not option.type in ['bool', 'unsigned', 'int', 'std::string']:
+    if not option.type in ['bool', 'unsigned', 'int', 'std::string',
+                           'std::vector<std::string>']:
       if enums.has_key(option.type):
         option.enum = enums[option.type]
       else:

clang/include/clang/Format/Format.h

@@ -120,7 +120,10 @@ struct FormatStyle {
   /// \brief The indentation used for namespaces.
   NamespaceIndentationKind NamespaceIndentation;
 
-  /// \brief The number of spaces to before trailing line comments.
+  /// \brief The number of spaces before trailing line comments (//-comments).
+  ///
+  /// This does not affect trailing block comments (/**/-comments) as those
+  /// commonly have different usage patterns and a number of special cases.
   unsigned SpacesBeforeTrailingComments;
 
   /// \brief If \c false, a function call's or function definition's parameters