From 91bb4467c50e3478b344e919141aa7ef49f7f25c Mon Sep 17 00:00:00 2001
From: Daniel Jasper <djasper@google.com>
Date: Wed, 9 Apr 2014 14:05:49 +0000
Subject: [PATCH] clang-format: Update flag documentation, and generation
 script.

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@205853 91177308-0d34-0410-b5e6-96231b3b80d8
---
 docs/ClangFormatStyleOptions.rst | 38 ++++++++++++++++++++++++--------
 docs/tools/dump_format_style.py  |  5 +++--
 include/clang/Format/Format.h    |  5 ++++-
 3 files changed, 36 insertions(+), 12 deletions(-)
 mode change 100644 => 100755 docs/tools/dump_format_style.py

diff --git a/docs/ClangFormatStyleOptions.rst b/docs/ClangFormatStyleOptions.rst
index db77372724..132e7f91ec 100644
--- a/docs/ClangFormatStyleOptions.rst
+++ b/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.
+
+  These are expected to be macros of the form:
+  \code
+  FOREACH(<variable-declaration>, ...)
+  <loop-body>
+  \endcode
 
-  For example, ``ForEachMacros: [BOOST_FOREACH, Q_FOREACH]`` tells
-  clang-format to treat ``BOOST_FOREACH`` and ``Q_FOREACH`` as loop control
-  statements.
+  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
diff --git a/docs/tools/dump_format_style.py b/docs/tools/dump_format_style.py
old mode 100644
new mode 100755
index addda2abc2..66bad8bb4e
--- a/docs/tools/dump_format_style.py
+++ b/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:
diff --git a/include/clang/Format/Format.h b/include/clang/Format/Format.h
index a671845b45..b601615a3f 100644
--- a/include/clang/Format/Format.h
+++ b/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
-- 
2.40.0