finalize docstring

Ultraplot · beckermr · Nov 20, 2025 · Nov 12, 2025 · Nov 12, 2025 · Nov 12, 2025
commit d5b2aa99bb281382dac0ece6ecaf89e439071b01
diff --git a/ultraplot/axes/plot.py b/ultraplot/axes/plot.py
@@ -4403,14 +4403,45 @@ def _apply_fill(
         stacked=None,
         **kwargs,
     ):
-        """
-        Apply area shading (fill_between / fill_betweenx) with seaborn helper tagging.
+        """Apply area shading using `fill_between` or `fill_betweenx`.
+
+        This is the internal implementation for `fill_between`, `fill_betweenx`,
+        `area`, and `areax`.
+
+        Parameters
+        ----------
+        xs, ys1, ys2 : array-like
+            The x and y coordinates for the shaded regions.
+        where : array-like, optional
+            A boolean mask for the points that should be shaded.
+        vert : bool, optional
+            The orientation of the shading. If `True` (default), `fill_between`
+            is used. If `False`, `fill_betweenx` is used.
+        negpos : bool, optional
+            Whether to use different colors for positive and negative shades.
+        stack : bool, optional
+            Whether to stack shaded regions.
+        **kwargs
+            Additional keyword arguments passed to the matplotlib fill function.
 
-        We tag seaborn-generated confidence interval / helper polygons as synthetic
-        unless the user explicitly supplies a label (label/labels/value/values or
-        shadelabel/fadelabel passed through error shading). Synthetic artists are
-        marked with _ultraplot_synthetic=True and given an underscore label so they
-        are ignored by legend collection.
+        Notes
+        -----
+        Special handling for plots from external packages (e.g., seaborn):
+
+        When this method is used in a context where plots are generated by
+        an external library like seaborn, it tags the resulting polygons
+        (e.g., confidence intervals) as "synthetic". This is done unless a
+        user explicitly provides a label.
+
+        Synthetic artists are marked with `_ultraplot_synthetic=True` and given
+        a label starting with an underscore (e.g., `_ultraplot_fill`). This
+        prevents them from being automatically included in legends, keeping the
+        legend clean and focused on user-specified elements.
+
+        Seaborn internally generates tags like "y", "ymin", and "ymax" for
+        vertical fills, and "x", "xmin", "xmax" for horizontal fills. UltraPlot
+        recognizes these and treats them as synthetic unless a different label
+        is provided.
         """
         # Parse input arguments
         kw = kwargs.copy()