From 99167c2c9b2e2c9e055f1ef406c8bd15643a51a3 Mon Sep 17 00:00:00 2001
From: Richard Si <63936253+ichard26@users.noreply.github.com>
Date: Sat, 2 Apr 2022 18:59:40 -0400
Subject: [PATCH] Moar code comments 'cause ASTs are no joke

---
 src/black/linegen.py | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/src/black/linegen.py b/src/black/linegen.py
index f1db761bc57..2cf9cf3130a 100644
--- a/src/black/linegen.py
+++ b/src/black/linegen.py
@@ -896,6 +896,22 @@ def normalize_invisible_parens(
 
 def remove_with_parens(node: Node, parent: Node) -> None:
     """Recursively hide optional parens in `with` statements."""
+    # Removing all unnecessary parentheses in with statements in one pass is a tad
+    # complex as different variations of bracketed statements result in pretty
+    # different parse trees:
+    #
+    # with (open("file")) as f:                       # this is an asexpr_test
+    #     ...
+    #
+    # with (open("file") as f):                       # this is an atom containing an
+    #     ...                                         # asexpr_test
+    #
+    # with (open("file")) as f, (open("file")) as f:  # this is asexpr_test, COMMA,
+    #     ...                                         # asexpr_test
+    #
+    # with (open("file") as f, open("file") as f):    # an atom containing a
+    #     ...                                         # testlist_gexp which then
+    #                                                 # contains multiple asexpr_test(s)
     if node.type == syms.atom:
         if maybe_make_parens_invisible_in_atom(
             node,