From 50726945719fb9b0dc62a1be999894411dadc03f Mon Sep 17 00:00:00 2001
From: Antony Lee <anntzer.lee@gmail.com>
Date: Mon, 20 Sep 2021 18:13:32 +0200
Subject: [PATCH] Docstring cleanups around DATA_PARAMETER_PLACEHOLDER.

- `[notes section required to get data note injection right]` has been
  obsoleted by DATA_PARAMETER_PLACEHOLDER; get rid of them.
- loglog, semilogx, semilogy are thin wrappers around plot; it seems
  fine to not document data there and leave it implicitly part of
  `**kwargs: all parameters supported by plot`.  Then "Other Parameters"
  only contains `**kwargs` whose description is quite short, so it can
  just be lifted into the main Parameters section rather than requiring
  a separate section just for itself.
- Likewise for `step`, but that method actually explicitly lists `data`
  in its signature, so just move its (already existing) description down
  to its correct position.

This change was motivated by the fact that DATA_PARAMETER_PLACEHOLDER is
not correctly handled for these simple plot() wrappers; because they all
operate without going through _preprocess_data(), fixing them would also
require their own ad-hoc solution anyways.
---
 lib/matplotlib/axes/_axes.py | 62 +++++++++---------------------------
 1 file changed, 15 insertions(+), 47 deletions(-)

diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
index cef0f8c3c88d..00adeb7747b4 100644
--- a/lib/matplotlib/axes/_axes.py
+++ b/lib/matplotlib/axes/_axes.py
@@ -1745,18 +1745,13 @@ def loglog(self, *args, **kwargs):
             Non-positive values can be masked as invalid, or clipped to a very
             small positive number.
 
+        **kwargs
+            All parameters supported by `.plot`.
+
         Returns
         -------
         list of `.Line2D`
             Objects representing the plotted data.
-
-        Other Parameters
-        ----------------
-        data : indexable object, optional
-            DATA_PARAMETER_PLACEHOLDER
-
-        **kwargs
-            All parameters supported by `.plot`.
         """
         dx = {k: v for k, v in kwargs.items()
               if k in ['base', 'subs', 'nonpositive',
@@ -1801,18 +1796,13 @@ def semilogx(self, *args, **kwargs):
             Non-positive values in x can be masked as invalid, or clipped to a
             very small positive number.
 
+        **kwargs
+            All parameters supported by `.plot`.
+
         Returns
         -------
         list of `.Line2D`
             Objects representing the plotted data.
-
-        Other Parameters
-        ----------------
-        data : indexable object, optional
-            DATA_PARAMETER_PLACEHOLDER
-
-        **kwargs
-            All parameters supported by `.plot`.
         """
         d = {k: v for k, v in kwargs.items()
              if k in ['base', 'subs', 'nonpositive',
@@ -1853,18 +1843,13 @@ def semilogy(self, *args, **kwargs):
             Non-positive values in y can be masked as invalid, or clipped to a
             very small positive number.
 
+        **kwargs
+            All parameters supported by `.plot`.
+
         Returns
         -------
         list of `.Line2D`
             Objects representing the plotted data.
-
-        Other Parameters
-        ----------------
-        data : indexable object, optional
-            DATA_PARAMETER_PLACEHOLDER
-
-        **kwargs
-            All parameters supported by `.plot`.
         """
         d = {k: v for k, v in kwargs.items()
              if k in ['base', 'subs', 'nonpositive',
@@ -2098,10 +2083,6 @@ def step(self, x, y, *args, where='pre', data=None, **kwargs):
             and plotted on the given positions, however, this is a rarely
             needed feature for step plots.
 
-        data : indexable object, optional
-            An object with labelled data. If given, provide the label names to
-            plot in *x* and *y*.
-
         where : {'pre', 'post', 'mid'}, default: 'pre'
             Define where the steps should be placed:
 
@@ -2113,22 +2094,17 @@ def step(self, x, y, *args, where='pre', data=None, **kwargs):
               value ``y[i]``.
             - 'mid': Steps occur half-way between the *x* positions.
 
-        Returns
-        -------
-        list of `.Line2D`
-            Objects representing the plotted data.
-
-        Other Parameters
-        ----------------
         data : indexable object, optional
-            DATA_PARAMETER_PLACEHOLDER
+            An object with labelled data. If given, provide the label names to
+            plot in *x* and *y*.
 
         **kwargs
             Additional parameters are the same as those for `.plot`.
 
-        Notes
-        -----
-        .. [notes section required to get data note injection right]
+        Returns
+        -------
+        list of `.Line2D`
+            Objects representing the plotted data.
         """
         _api.check_in_list(('pre', 'post', 'mid'), where=where)
         kwargs['drawstyle'] = 'steps-' + where
@@ -5148,10 +5124,6 @@ def _fill_between_x_or_y(
         --------
         fill_between : Fill between two sets of y-values.
         fill_betweenx : Fill between two sets of x-values.
-
-        Notes
-        -----
-        .. [notes section required to get data note injection right]
         """
 
         dep_dir = {"x": "y", "y": "x"}[ind_dir]
@@ -6227,10 +6199,6 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
         **kwargs
             Supported additional parameters depend on the type of grid.
             See return types of *image* for further description.
-
-        Notes
-        -----
-        .. [notes section required to get data note injection right]
         """
 
         C = args[-1]