[clang-format] Add ability to wrap braces after multi-line control statements

Summary:
Change the BraceWrappingFlags' AfterControlStatement from a bool to an enum with three values:

* "Never": This is the default, and does not do any brace wrapping after control statements.
* "MultiLine": This only wraps braces after multi-line control statements (this really only happens when a ColumnLimit is specified).
* "Always": This always wraps braces after control statements.

The first and last options are backwards-compatible with "false" and "true", respectively.

The new "MultiLine" option is useful for when a wrapped control statement's indentation matches the subsequent block's indentation. It makes it easier to see at a glance where the control statement ends and where the block's code begins. For example:

```
if (
  foo
  && bar )
{
  baz();
}
```

vs.

```
if (
  foo
  && bar ) {
  baz();
}
```

Short control statements (1 line) do not wrap the brace to the next line, e.g.

```
if (foo) {
  bar();
} else {
  baz();
}
```

Reviewers: sammccall, owenpan, reuk, MyDeveloperDay, klimek

Reviewed By: MyDeveloperDay

Subscribers: MyDeveloperDay, cfe-commits

Patch By: mitchell-stellar

Tags: #clang-format, #clang, #clang-tools-extra

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

llvm-svn: 373647

1 files changed, 37 insertions, 15 deletions

diff --git a/clang/docs/ClangFormatStyleOptions.rst b/clang/docs/ClangFormatStyleOptions.rst
index 0803e65df2e..c7f47c5c021 100644
--- a/clang/docs/ClangFormatStyleOptions.rst
+++ b/clang/docs/ClangFormatStyleOptions.rst
@@ -778,24 +778,46 @@ the configuration (without a prefix: ``Auto``).
       class foo
       {};
 
-  * ``bool AfterControlStatement`` Wrap control statements (``if``/``for``/``while``/``switch``/..).
+  * ``BraceWrappingAfterControlStatementStyle AfterControlStatement``
+    Wrap control statements (``if``/``for``/``while``/``switch``/..).
 
-    .. code-block:: c++
+    Possible values:
 
-      true:
-      if (foo())
-      {
-      } else
-      {}
-      for (int i = 0; i < 10; ++i)
-      {}
+    * ``BWACS_Never`` (in configuration: ``Never``)
+      Never wrap braces after a control statement.
 
-      false:
-      if (foo()) {
-      } else {
-      }
-      for (int i = 0; i < 10; ++i) {
-      }
+      .. code-block:: c++
+
+        if (foo()) {
+        } else {
+        }
+        for (int i = 0; i < 10; ++i) {
+        }
+
+    * ``BWACS_MultiLine`` (in configuration: ``MultiLine``)
+      Only wrap braces after a multi-line control statement.
+
+      .. code-block:: c++
+
+        if (foo && bar &&
+            baz)
+        {
+          quux();
+        }
+        while (foo || bar) {
+        }
+
+    * ``BWACS_Always`` (in configuration: ``Always``)
+      Always wrap braces after a control statement.
+
+      .. code-block:: c++
+
+        if (foo())
+        {
+        } else
+        {}
+        for (int i = 0; i < 10; ++i)
+        {}
 
   * ``bool AfterEnum`` Wrap enum definitions.