DOC: Some small additions to the API docs

timhoffm · timhoffm · commit 8cc21b4312c1 · 2026-01-13T16:34:00.000+01:00
diff --git a/doc/api/artist_api.rst b/doc/api/artist_api.rst
@@ -122,6 +122,7 @@ Figure and Axes
 
    Artist.set_figure
    Artist.get_figure
+   Artist.figure
 
 Children
 --------
diff --git a/doc/api/axes_api.rst b/doc/api/axes_api.rst
@@ -628,6 +628,8 @@ Other
    Axes.get_transformed_clip_path_and_affine
    Axes.has_data
    Axes.set
+   Axes.get_figure
+   Axes.figure
    Axes.remove
 
 .. autoclass:: matplotlib.axes.Axes.ArtistList
diff --git a/doc/missing-references.json b/doc/missing-references.json
@@ -4,7 +4,7 @@
       "<unknown>:1"
     ],
     "matplotlib.axes._base._AxesBase": [
-      "doc/api/artist_api.rst:202"
+      "doc/api/artist_api.rst:203"
     ],
     "matplotlib.backend_bases._Backend": [
       "lib/matplotlib/backend_bases.py:docstring of matplotlib.backend_bases.ShowBase:1"
@@ -18,7 +18,7 @@
       "lib/matplotlib/backends/backend_tkcairo.py:docstring of matplotlib.backends.backend_tkcairo.FigureCanvasTkCairo:1"
     ],
     "matplotlib.image._ImageBase": [
-      "doc/api/artist_api.rst:202",
+      "doc/api/artist_api.rst:203",
       "lib/matplotlib/image.py:docstring of matplotlib.image.AxesImage:1",
       "lib/matplotlib/image.py:docstring of matplotlib.image.BboxImage:1",
       "lib/matplotlib/image.py:docstring of matplotlib.image.FigureImage:1"
@@ -67,7 +67,7 @@
       "lib/matplotlib/projections/geo.py:docstring of matplotlib.projections.geo.MollweideAxes.MollweideTransform:1"
     ],
     "matplotlib.text._AnnotationBase": [
-      "doc/api/artist_api.rst:202",
+      "doc/api/artist_api.rst:203",
       "lib/matplotlib/offsetbox.py:docstring of matplotlib.offsetbox.AnnotationBbox:1",
       "lib/matplotlib/text.py:docstring of matplotlib.text.Annotation:1"
     ],
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -165,10 +165,24 @@ def _update_set_signature_and_docstring(cls):
                if prop not in Artist._PROPERTIES_EXCLUDED_FROM_SET]])
         cls.set._autogenerated_signature = True
 
-        cls.set.__doc__ = (
-            "Set multiple properties at once.\n\n"
-            "Supported properties are\n\n"
-            + kwdoc(cls))
+        cls.set.__doc__ = ("""\
+Set multiple properties at once.
+
+::
+    a.set(a=A, b=B, c=C)
+
+is equivalent to ::
+
+    a.set_a(A)
+    a.set_b(B)
+    a.set_c(C)
+
+The order of operations is not guaranteed, however most properties do not
+depend on each other.
+
+Supported properties are
+
+""" + kwdoc(cls))
 
     def __init__(self):
         self._stale = True
