Fix typo in diff_shades.yml workflow (#2778)

[etc/vim.git] / 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 00001dbc461cebd03837216ca6b8f6e7d113294b..11fe2c8cceb6fe84b8690b102b73fb410328090e 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.
 
+### 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
@@ -223,10 +233,10 @@ _Black_ prefers double quotes (`"` and `"""`) over single quotes (`'` and `'''`)
 will replace the latter with the former as long as it does not result in more backslash
 escapes than before.
 
-_Black_ also standardizes string prefixes, making them always lowercase. On top of that,
-if your code is already Python 3.6+ only or it's using the `unicode_literals` future
-import, _Black_ will remove `u` from the string prefix as it is meaningless in those
-scenarios.
+_Black_ also standardizes string prefixes. Prefix characters are made lowercase with the
+exception of [capital "R" prefixes](#rstrings-and-rstrings), unicode literal markers
+(`u`) are removed because they are meaningless in Python 3, and in the case of multiple
+characters "r" is put first as in spoken language: "raw f-string".
 
 The main reason to standardize on a single form of quotes is aesthetics. Having one kind
 of quotes everywhere reduces reader distraction. It will also enable a future version of
@@ -250,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
@@ -263,14 +275,13 @@ for both quotations and the text within, although relative indentation in the te
 preserved. Superfluous trailing whitespace on each line and unnecessary new lines at the
 end of the docstring are removed. All leading tabs are converted to spaces, but tabs
 inside text are preserved. Whitespace leading and trailing one-line docstrings is
-removed. The quotations of an empty docstring are separated with one space.
+removed.
 
 ### Numeric literals
 
 _Black_ standardizes most numeric literals to use lowercase letters for the syntactic
 parts and uppercase letters for the digits themselves: `0xAB` instead of `0XAB` and
-`1e10` instead of `1E10`. Python 2 long literals are styled as `2L` instead of `2l` to
-avoid confusion between `l` and `1`.
+`1e10` instead of `1E10`.
 
 ### Line breaks & binary operators