From eb5d175c9cd3c14a0731f8afd0cc5a18264353e7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Felix=20Hild=C3=A9n?= <felix.hilden@gmail.com>
Date: Mon, 27 Jun 2022 23:24:34 +0300
Subject: [PATCH] Update preview style docs to include recent changes (#3136)

Covers GH-2926, GH-2990, GH-2991, and GH-3035.

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
---
 docs/the_black_code_style/future_style.md | 60 ++++++++++++++++++++---
 1 file changed, 52 insertions(+), 8 deletions(-)

diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
index 8d159e9b0a2..fab4bca120e 100644
--- a/docs/the_black_code_style/future_style.md
+++ b/docs/the_black_code_style/future_style.md
@@ -50,27 +50,71 @@ limit. Line continuation backslashes are converted into parenthesized strings.
 Unnecessary parentheses are stripped. The stability and status of this feature is
 tracked in [this issue](https://github.com/psf/black/issues/2188).
 
-### Removing trailing newlines after code block open
+### Removing newlines in the beginning of code blocks
 
-_Black_ will remove trailing newlines after code block openings. That means that the
-following code:
+_Black_ will remove newlines in the beginning of new code blocks, i.e. when the
+indentation level is increased. For example:
 
 ```python
 def my_func():
 
     print("The line above me will be deleted!")
-
-    print("But the line above me won't!")
 ```
 
-Will be changed to:
+will be changed to:
 
 ```python
 def my_func():
     print("The line above me will be deleted!")
-
-    print("But the line above me won't!")
 ```
 
 This new feature will be applied to **all code blocks**: `def`, `class`, `if`, `for`,
 `while`, `with`, `case` and `match`.
+
+### Improved parentheses management
+
+_Black_ will format parentheses around return annotations similarly to other sets of
+parentheses. For example:
+
+```python
+def foo() -> (int):
+    ...
+
+def foo() -> looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong:
+    ...
+```
+
+will be changed to:
+
+```python
+def foo() -> int:
+    ...
+
+
+def foo() -> (
+    looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong
+):
+    ...
+```
+
+And, extra parentheses in `await` expressions and `with` statements are removed. For
+example:
+
+```python
+with ((open("bla.txt")) as f, open("x")):
+    ...
+
+async def main():
+    await (asyncio.sleep(1))
+```
+
+will be changed to:
+
+```python
+with open("bla.txt") as f, open("x"):
+    ...
+
+
+async def main():
+    await asyncio.sleep(1)
+```