Proof of concept for adding kwdoc content to properties using a decorator

timhoffm · timhoffm · commit 2795d8329cf8 · 2022-03-24T23:06:28.000+01:00
diff --git a/lib/matplotlib/_docstring.py b/lib/matplotlib/_docstring.py
@@ -3,6 +3,19 @@
 from . import _api
 
 
+def artist_property(kwdoc):
+    """
+    Decorator to be applied to artist property setters.
+
+    The given text is stored in a privat variable ``_kwdoc`` on the method.
+    It is used for generating the kwdoc list for artists.
+    """
+    def decorator(func):
+        func._kwdoc = kwdoc
+        return func
+    return decorator
+
+
 class Substitution:
     """
     A decorator that performs %-substitution on an object's docstring.
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -1433,6 +1433,9 @@ def get_valid_values(self, attr):
             raise AttributeError('%s has no function %s' % (self.o, name))
         func = getattr(self.o, name)
 
+        if hasattr(func, '_kwdoc'):
+            return func._kwdoc
+
         docstring = inspect.getdoc(func)
         if docstring is None:
             return 'unknown'
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
@@ -1268,6 +1268,7 @@ def set_fontproperties(self, fp):
         self._fontproperties = FontProperties._from_any(fp).copy()
         self.stale = True
 
+    @_docstring.artist_property(kwdoc="bool, default: :rc:`text.usetex`")
     def set_usetex(self, usetex):
         """
         Parameters
