X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/62bfbd6a63dcac2f6f31eb014f69397c9eb967d2..05b54b8:/docs/the_black_code_style/current_style.md

diff --git a/docs/the_black_code_style/current_style.md b/docs/the_black_code_style/current_style.md
index 7d08bc9..aa2dd88 100644
--- a/docs/the_black_code_style/current_style.md
+++ b/docs/the_black_code_style/current_style.md
@@ -128,29 +128,9 @@ indentation level (like the arguments list and the docstring in the example abov
 If a data structure literal (tuple, list, set, dict) or a line of "from" imports cannot
 fit in the allotted length, it's always split into one element per line. This minimizes
 diffs as well as enables readers of code to find which commit introduced a particular
-entry. This also makes _Black_ compatible with [isort](https://pypi.org/p/isort/) with
-the following configuration.
-
-<details>
-<summary>A compatible `.isort.cfg`</summary>
-
-```cfg
-[settings]
-multi_line_output = 3
-include_trailing_comma = True
-force_grid_wrap = 0
-use_parentheses = True
-ensure_newline_before_comments = True
-line_length = 88
-```
-
-The equivalent command line is:
-
-```
-$ isort --multi-line=3 --trailing-comma --force-grid-wrap=0 --use-parentheses --line-width=88 [ file.py ]
-```
-
-</details>
+entry. This also makes _Black_ compatible with
+[isort](../guides/using_black_with_other_tools.md#isort) with the ready-made `black`
+profile or manual configuration.
 
 ### Line length
 
@@ -220,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
@@ -270,6 +260,8 @@ If you are adopting _Black_ in a large project with pre-existing string conventi
 you can pass `--skip-string-normalization` on the command line. This is meant as an
 adoption helper, avoid using this for new projects.
 
+(labels/experimental-string)=
+
 As an experimental option (can be enabled by `--experimental-string-processing`),
 _Black_ splits long strings (using parentheses where appropriate) and merges short ones.
 When split, parts of f-strings that don't need formatting are converted to plain