Repository: matplotlib/matplotlib
File: lib/matplotlib/_docstring.py (Python)

Code before:
import inspect

from . import _api


def kwarg_doc(text):
    """
    Decorator for defining the documentation used when artist properties are
    passed through as keyword arguments.

    See e.g. the `**kwargs` section in `.Axes.text`.

    The given text is stored in a privat variable ``_kwarg_doc`` on the method.
    It is used for generating the kwdoc list for artists, which we
    auto-generate through docstring interpolation, e.g. via
    ``%(Line2D:kwdoc)s``.

    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):

    """
    def decorator(func):
        func._kwarg_doc = text
        return func
    return decorator


class Substitution:
    """
    A decorator that performs %-substitution on an object's docstring.

    This decorator should be robust even if ``obj.__doc__`` is None (for
    example, if -OO was passed to the interpreter).

    Usage: construct a docstring.Substitution with a sequence or dictionary
    suitable for performing substitution; then decorate a suitable function
    with the constructed object, e.g.::

        sub_author_name = Substitution(author='Jason')

        @sub_author_name
        def some_function(x):
            "%(author)s wrote this function"

Review comment (bug):
I agree it's pretty mysterious from this text.  Suggest more explanation, though the following is probably incorrect.  The docstring should motivate why this is helpful and what effect it has on the documentation.  

```suggestion
    """
    Decorator on property setters for defining the documentation used when artist 
    properties are passed through as keyword arguments.

    We generate lists of kwargs by inspecting the properties on a class, and then refer to them 
    in the documentation as, for example, ``%(Text:kwdoc)s``, which is used in the `**kwargs` 
    section in `.Axes.text`.  However, sometimes the setter function parameter description is
    not what we want in this generated list.  

    This method adds the given text to a private variable ``_kwarg_doc`` on the class.
    It will be used for generating the kwdoc list for artists instead of the parameter docs.  

    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):
```

Code after:
import inspect

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.

    This decorator should be robust even if ``obj.__doc__`` is None (for
    example, if -OO was passed to the interpreter).

    Usage: construct a docstring.Substitution with a sequence or dictionary
    suitable for performing substitution; then decorate a suitable function
    with the constructed object, e.g.::

        sub_author_name = Substitution(author='Jason')