From a9eab85f226df3b3070aca122d089dbd62b42b9c Mon Sep 17 00:00:00 2001 From: =?utf8?q?Felix=20Hild=C3=A9n?= Date: Wed, 9 Jun 2021 00:57:23 +0300 Subject: [PATCH] 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 --- docs/the_black_code_style/current_style.md | 10 ++++++++++ tests/data/comments2.py | 4 ++-- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md index 8c3a302..aa2dd88 100644 --- 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. +### 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 diff --git a/tests/data/comments2.py b/tests/data/comments2.py index 221cb3f..4eea013 100644 --- 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 @@ -336,7 +336,7 @@ class Test: ####################### -instruction() +instruction() # comment with bad spacing # END COMMENTS # MORE END COMMENTS -- 2.39.5