Clarify current trailing comma behavior in the docs

diff --git a/docs/the_black_code_style.md b/docs/the_black_code_style.md
index 735e9c015d70d468a723a5e6d361ed766b096c43..19464ba482a083e6d46d3f4db09ce2ec3d4a8c6d 100644 (file)
--- 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