Tighten verbose docstrings and comments

Drop multi-paragraph regression-narrative blocks in favor of one-line
docstrings naming the invariant under test. Strip restating-the-bug
inline comments inside parametrize tables.

Author: timtreis

src/spatialdata_plot/pl/_datashader.py

@@ -44,11 +44,10 @@
 
 
 def _apply_user_alpha(result: ds.tf.Image | np.ndarray, alpha: float) -> ds.tf.Image | np.ndarray:
-    """Multiply the alpha channel of a datashader shade result by ``alpha``.
+    """Scale the alpha channel of a datashader shade result by ``alpha``.
 
-    ``ds.tf.shade(min_alpha=...)`` is a floor on the alpha of non-empty pixels,
-    not a scaling factor, so user-supplied ``fill_alpha`` / ``alpha`` must be
-    applied post-hoc to match the matplotlib path. See #617.
+    ``ds.tf.shade(min_alpha=...)`` is a floor, not a scale, so user alpha
+    must be applied post-hoc. See #617.
     """
     if alpha >= 1.0 or result is None:
         return result

tests/pl/test_render_shapes.py

@@ -1238,13 +1238,7 @@ def test_datashader_alpha_not_applied_twice(sdata_blobs: SpatialData):
     ],
 )
 def test_datashader_respects_fill_alpha(sdata_blobs: SpatialData, fill_alpha: float, expected_max: int):
-    """Datashader must apply fill_alpha as a multiplicative scale on the rendered alpha.
-
-    Regression test for https://github.com/scverse/spatialdata-plot/issues/617.
-    Before the fix, ``fill_alpha`` was passed only as ``ds.tf.shade(min_alpha=...)``,
-    which is a floor on alpha for non-empty pixels rather than a scaling factor, so
-    shapes always rendered at alpha=255 regardless of ``fill_alpha`` (including 0.0).
-    """
+    """fill_alpha must scale the rendered alpha channel linearly on the datashader path (#617)."""
     fig, ax = plt.subplots()
     sdata_blobs.pl.render_shapes(
         element="blobs_polygons",
@@ -1264,20 +1258,14 @@ def test_datashader_respects_fill_alpha(sdata_blobs: SpatialData, fill_alpha: fl
 @pytest.mark.parametrize(
     ("outline_alpha", "expected_max"),
     [
-        (0.0, None),  # no outline image is rendered
+        (0.0, None),
         (0.3, 76),
         (0.5, 127),
         (1.0, 255),
     ],
 )
 def test_datashader_respects_outline_alpha(sdata_blobs: SpatialData, outline_alpha: float, expected_max: int | None):
-    """Datashader must apply outline_alpha as a multiplicative scale on the rendered alpha.
-
-    Regression test for https://github.com/scverse/spatialdata-plot/issues/617.
-    Same root cause as fill_alpha: ``outline_alpha`` was passed only as
-    ``ds.tf.shade(min_alpha=...)``, which is a floor on alpha for non-empty pixels,
-    so outlines always rendered with max alpha=255 regardless of ``outline_alpha``.
-    """
+    """outline_alpha must scale the outline image's alpha; alpha=0 must skip rendering entirely (#617)."""
     fig, ax = plt.subplots()
     sdata_blobs.pl.render_shapes(
         element="blobs_polygons",
@@ -1289,18 +1277,16 @@ def test_datashader_respects_outline_alpha(sdata_blobs: SpatialData, outline_alp
     fig.canvas.draw()
 
     axes_images = [c for c in ax.get_children() if isinstance(c, matplotlib.image.AxesImage)]
-    # The outline is rendered red on top of the (gray) fill; pick the red one.
     outline_imgs = [
         img
         for img in axes_images
         if (arr := img.get_array()).ndim == 3 and arr.shape[-1] == 4 and arr[..., 0].max() > arr[..., 1].max()
     ]
     if expected_max is None:
-        assert not outline_imgs, "outline_alpha=0 should not render an outline image"
+        assert not outline_imgs
     else:
-        assert outline_imgs, "no outline AxesImage found"
-        rgba = outline_imgs[0].get_array()
-        assert int(rgba[..., 3].max()) == expected_max
+        assert outline_imgs
+        assert int(outline_imgs[0].get_array()[..., 3].max()) == expected_max
     plt.close(fig)
 
 

tests/pl/test_utils.py

@@ -169,19 +169,15 @@ def test_is_color_like(color_result: tuple[ColorLike, bool]):
 @pytest.mark.parametrize(
     ("outline_alpha", "outline_color", "expected"),
     [
-        # Explicit outline_alpha=0.0 with outline_color: previously a falsy
-        # short-circuit (`outline_alpha and outline_alpha == 0.0`) caused
-        # outline_alpha=0.0 to be silently remapped to (1.0, 1.0), rendering
-        # the outline anyway. Regression test for the #617 follow-up.
         (0.0, Color("#ff0000"), (0.0, 0.0)),
         (0, Color("#ff0000"), (0.0, 0.0)),
         ((0.0, 0.0), Color("#ff0000"), (0.0, 0.0)),
-        # Sanity: positive alphas still produce a visible outline.
         (0.5, Color("#ff0000"), (0.5, 0.0)),
         (1.0, Color("#ff0000"), (1.0, 0.0)),
     ],
 )
 def test_set_outline_respects_zero_alpha(outline_alpha, outline_color, expected):
+    """outline_alpha=0 must yield (0.0, 0.0) even when outline_color is set (#617 follow-up)."""
     alpha, _ = _set_outline(outline_alpha=outline_alpha, outline_width=None, outline_color=outline_color)
     assert alpha == expected