Docs: Expand preview style features documentation with examples (psf#4987)

veeceey · claude · web-flow · commit 9d05e1504b06 · 2026-02-20T20:45:36.000-06:00
* Docs: Expand preview style features documentation with examples Adds detailed descriptions and code examples for preview style features that previously only had single-line descriptions, addressing issue psf#4429. Changes: - Add dedicated section for `wrap_comprehension_in` feature: - Explanation of when and why comprehensions are wrapped - Examples with list comprehensions - Examples with dictionary comprehensions - Add dedicated section for `simplify_power_operator_hugging` feature: - Explanation of power operator whitespace handling - Examples with simple expressions - Examples with split expressions - Updated feature list to link to the new detailed sections This brings the preview features documentation in line with the unstable features documentation style, which already includes detailed sections and examples for each feature. Fixes psf#4429 * Add changelog entry for preview style docs expansion (psf#4987) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix power operator example per review --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
diff --git a/CHANGES.md b/CHANGES.md
@@ -59,6 +59,10 @@
 <!-- Major changes to documentation and policies. Small docs changes
      don't need a changelog entry. -->
 
+- Expand preview style documentation with detailed examples for `wrap_comprehension_in`,
+  `simplify_power_operator_hugging`, and `wrap_long_dict_values_in_parens` features
+  (#4987)
+
 ## 26.1.0
 
 ### Highlights
diff --git a/docs/the_black_code_style/future_style.md b/docs/the_black_code_style/future_style.md
@@ -15,12 +15,92 @@ Currently, the following features are included in the preview style:
 
 - `wrap_comprehension_in`: Wrap the `in` clause of list and dictionary comprehensions
   across lines if it would otherwise exceed the maximum line length.
+  ([see below](labels/wrap-comprehension-in))
 - `simplify_power_operator_hugging`: Use a simpler implementation of the power operator
   "hugging" logic (removing whitespace around `**` in simple expressions), which applies
   also in the rare case the exponentiation is split into separate lines.
+  ([see below](labels/simplify-power-operator))
 - `wrap_long_dict_values_in_parens`: Add parentheses around long values in dictionaries.
   ([see below](labels/wrap-long-dict-values))
 
+(labels/wrap-comprehension-in)=
+
+### Wrapping long comprehension `in` clauses
+
+When a list or dictionary comprehension has a long `in` clause that would exceed the
+maximum line length, Black will wrap it across multiple lines for better readability.
+This helps keep comprehensions readable when the iterable expression is complex or
+lengthy.
+
+For example:
+
+```python
+# Before
+result = [item.process() for item in some_very_long_function_name(argument1, argument2, argument3)]
+```
+
+will be formatted to:
+
+```python
+# After
+result = [
+    item.process()
+    for item in some_very_long_function_name(
+        argument1, argument2, argument3
+    )
+]
+```
+
+This also applies to dictionary comprehensions:
+
+```python
+# Before
+mapping = {key: value.transform() for key, value in get_items_from_very_long_source(param1, param2)}
+```
+
+will be formatted to:
+
+```python
+# After
+mapping = {
+    key: value.transform()
+    for key, value in get_items_from_very_long_source(
+        param1, param2
+    )
+}
+```
+
+(labels/simplify-power-operator)=
+
+### Simplified power operator whitespace handling
+
+Black's power operator "hugging" logic removes whitespace around `**` in simple
+expressions (e.g., `x**2` instead of `x ** 2`). This feature uses a simpler, more
+consistent implementation that also applies when exponentiation is split across lines.
+
+For example:
+
+```python
+# Simple expressions - whitespace is removed
+result = x**2 + y**3
+value = base**exponent
+```
+
+When the exponentiation is split across lines (rare), the simplified logic ensures
+consistent formatting:
+
+```python
+# Complex expression split across lines
+result = (
+    some_very_long_base_expression
+    **some_very_long_exponent_expression
+    **some_very_long_third_expression
+)
+```
+
+This feature primarily improves the internal consistency of Black's formatting logic
+rather than making dramatic visual changes to most code.
+
 (labels/wrap-long-dict-values)=
 
 ### Improved parentheses management in dicts
