X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/573b8de54470dbad8bcaaebd5a28dad507c44666..e0d766727dc87f5c5f39ef751d0bf23fc5ff31a0:/docs/the_black_code_style.md

diff --git a/docs/the_black_code_style.md b/docs/the_black_code_style.md
index 735e9c0..a4e55c1 100644
--- a/docs/the_black_code_style.md
+++ b/docs/the_black_code_style.md
@@ -244,16 +244,6 @@ required due to an inner function starting immediately after.
 _Black_ will add trailing commas to expressions that are split by comma where each
 element is on its own line. This includes function signatures.
 
-Unnecessary trailing commas are removed if an expression fits in one line. This makes it
-1% more likely that your line won't exceed the allotted line length limit. Moreover, in
-this scenario, if you added another argument to your call, you'd probably fit it in the
-same line anyway. That doesn't make diffs any larger.
-
-One exception to removing trailing commas is tuple expressions with just one element. In
-this case _Black_ won't touch the single trailing comma as this would unexpectedly
-change the underlying data type. Note that this is also the case when commas are used
-while indexing. This is a tuple in disguise: `numpy_array[3, ]`.
-
 One exception to adding trailing commas is function signatures containing `*`, `*args`,
 or `**kwargs`. In this case a trailing comma is only safe to use on Python 3.6. _Black_
 will detect if your file is already 3.6+ only and use trailing commas in this situation.
@@ -262,6 +252,10 @@ in function signatures that have stars in them. In other words, if you'd like a
 comma in this situation and _Black_ didn't recognize it was safe to do so, put it there
 manually and _Black_ will keep it.
 
+A pre-existing trailing comma informs _Black_ to always explode contents of the current
+bracket pair into one item per line. Read more about this in the
+[Pragmatism](#pragmatism) section below.
+
 ### Strings
 
 _Black_ prefers double quotes (`"` and `"""`) over single quotes (`'` and `'''`). It
@@ -444,6 +438,9 @@ into one item per line.
 How do you make it stop? Just delete that trailing comma and _Black_ will collapse your
 collection into one line if it fits.
 
+If you must, you can recover the behaviour of early versions of Black with the option
+`--skip-magic-trailing-comma` / `-C`.
+
 ### r"strings" and R"strings"
 
 _Black_ normalizes string quotes as well as string prefixes, making them lowercase. One