Mention comment non-processing in documentation (#2306)

This commit adds a short section discussing the non-processing of docstrings
besides spacing improvements, mentions comment moving and links to the
AST equivalence discussion. I also added a simple spacing test for good
measure.

Commit history before merge:

* Mention comment non-processing in documentation, add spacing test
* Mention special cases for comment spacing
* Add all special cases, improve wording

diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 8c3a30270d1347dcd1a6b89fe448d9f3947a68bd..aa2dd881a9ea8a520673a9eb951b3844489c66d5 100644 (file)
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -200,6 +200,16 @@ following field or method. This conforms to
 _Black_ won't insert empty lines after function docstrings unless that empty line is
 required due to an inner function starting immediately after.
 
 _Black_ won't insert empty lines after function docstrings unless that empty line is
 required due to an inner function starting immediately after.
 

+### Comments
+
+_Black_ does not format comment contents, but it enforces two spaces between code and a
+comment on the same line, and a space before the comment text begins. Some types of
+comments that require specific spacing rules are respected: doc comments (`#: comment`),
+section comments with long runs of hashes, and Spyder cells. Non-breaking spaces after
+hashes are also preserved. Comments may sometimes be moved because of formatting
+changes, which can break tools that assign special meaning to them. See
+[AST before and after formatting](#ast-before-and-after-formatting) for more discussion.
+

 ### Trailing commas
 
 _Black_ will add trailing commas to expressions that are split by comma where each
 ### Trailing commas
 
 _Black_ will add trailing commas to expressions that are split by comma where each

diff --git a/tests/data/comments2.py b/tests/data/comments2.py
index 221cb3fe143ad28877c88ad92560a931564d041d..4eea013151a1f205fd4ae074b35293dc686014ae 100644 (file)
--- a/tests/data/comments2.py
+++ b/tests/data/comments2.py
@@ -159,7 +159,7 @@ class Test:
 #######################
 
 
 #######################
 
 

-instruction()
+instruction()#comment with bad spacing

 
 # END COMMENTS
 # MORE END COMMENTS
 
 # END COMMENTS
 # MORE END COMMENTS


@@ -336,7 +336,7 @@ class Test:
 #######################
 
 
 #######################
 
 

-instruction()
+instruction()  # comment with bad spacing

 
 # END COMMENTS
 # MORE END COMMENTS
 
 # END COMMENTS
 # MORE END COMMENTS