From aaf53c9d4b7d014daacf6dcaa3ac30d8306aa66b Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Thu, 24 Mar 2022 23:06:28 +0100
Subject: [PATCH] Proof of concept for adding kwdoc content to properties using
 a decorator

---
 lib/matplotlib/_docstring.py  | 28 ++++++++++++++++++++++++++++
 lib/matplotlib/_docstring.pyi |  3 +++
 lib/matplotlib/artist.py      |  3 +++
 lib/matplotlib/text.py        |  1 +
 4 files changed, 35 insertions(+)

diff --git a/lib/matplotlib/_docstring.py b/lib/matplotlib/_docstring.py
index ecd209ca0853..b49d5b43f068 100644
--- a/lib/matplotlib/_docstring.py
+++ b/lib/matplotlib/_docstring.py
@@ -3,6 +3,34 @@
 from . import _api
 
 
+def kwarg_doc(text):
+    """
+    Decorator for defining the kwdoc documentation of artist properties.
+
+    This decorator can be applied to artist property setter methods.
+    The given text is stored in a privat attribute ``_kwarg_doc`` on
+    the method.  It is used to overwrite auto-generated documentation
+    in the *kwdoc list* for artists. The kwdoc list is used to document
+    ``**kwargs`` when they are properties of an artist. See e.g. the
+    ``**kwargs`` section in `.Axes.text`.
+
+    The text should contain the supported types as well as the default value
+    if applicable, e.g.:
+
+        @_docstring.kwarg_doc("bool, default: :rc:`text.usetex`")
+        def set_usetex(self, usetex):
+
+    See Also
+    --------
+    matplotlib.artist.kwdoc
+
+    """
+    def decorator(func):
+        func._kwarg_doc = text
+        return func
+    return decorator
+
+
 class Substitution:
     """
     A decorator that performs %-substitution on an object's docstring.
diff --git a/lib/matplotlib/_docstring.pyi b/lib/matplotlib/_docstring.pyi
index 0377dc5fe95b..bcb4b29ab922 100644
--- a/lib/matplotlib/_docstring.pyi
+++ b/lib/matplotlib/_docstring.pyi
@@ -4,6 +4,9 @@ from typing import Any, Callable, TypeVar, overload
 _T = TypeVar('_T')
 
 
+def kwarg_doc(text: str) -> Callable[[_T], _T]: ...
+
+
 class Substitution:
     @overload
     def __init__(self, *args: str): ...
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
index d0db945ab3e5..212a1c99241d 100644
--- a/lib/matplotlib/artist.py
+++ b/lib/matplotlib/artist.py
@@ -1482,6 +1482,9 @@ def get_valid_values(self, attr):
             raise AttributeError(f'{self.o} has no function {name}')
         func = getattr(self.o, name)
 
+        if hasattr(func, '_kwarg_doc'):
+            return func._kwarg_doc
+
         docstring = inspect.getdoc(func)
         if docstring is None:
             return 'unknown'
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
index 8734131dddc9..f328c89d6559 100644
--- a/lib/matplotlib/text.py
+++ b/lib/matplotlib/text.py
@@ -1314,6 +1314,7 @@ def set_fontproperties(self, fp):
         self._fontproperties = FontProperties._from_any(fp).copy()
         self.stale = True
 
+    @_docstring.kwarg_doc("bool, default: :rc:`text.usetex`")
     def set_usetex(self, usetex):
         """
         Parameters