I think this looks great! Can also be used to provide information for methods with inherited doc-strings (if that cannot be solved in some other way, e.g., clip_on for Text).

Suggested way forward:

1. Support parameterless @_docstring.kwdoc(), which uses the existing logic from ArtistInspector.get_valid_values to extract the values from the docstring. This saves us duplication of the values documentation if setters and the kwdoc are the same.
2. Flag all artist setters with this decorator. For simplicity start with the parameterless version everywhere.
3. Simplify the logic in ArtistInspector.get_setters to look for set_* methods with a _kwdoc attribute. (As an in-between check, make sure that the current logic and the _kwdoc logic match the same methods (i.e. we haven't forgotten to flag any setters).
4. Once the mechanism is in place, we can start adding more targeted kwdocs. (Can be a separate PR and doesn't have to be all at once).

I hold this off for now, because I think it's worth to establish explicit declaration of artist properties and make the kwdoc a part of that. See #22749 for the way forward.

I've put #22749 on hold and am back here. Let's take this step by step: Here is the first step that allows to explicitly set content for kwdoc entries.

Side note: IMHO it's not yet clear whether we'll keep the decorator only for kwdoc in the long run or whether it will grow additional functionality. But that's ok, we can always refactor and rename later because this is private API.

This seem reasonable to me and will merge the full rollout 👍🏻

I guess one may even consider adding a simpler version just containing the rcparam? Like @_docstring.rcparam("text.parse_math'). If the current parameter description does not contain the "or None"-part it will basically be

current_type + f", default: :rc:`{rcparam}`"

(I guess that the rcparam name is quite related, but maybe not related enough to automatically add that?)

I guess one may even consider adding a simpler version just containing the rcparam? Like @_docstring.rcparam("text.parse_math').

That depends on the definition of "simple" 😄. I'd argue:

Taking the given string and using it as the kwarg doc entry is pretty simple. Parsing the docstring (maybe stripping None (?)) and putting this plus the given string into a template string is more complex.
Also the former is more explicit.

On a general note: There's a strong believe among developers that duplication is a bad thing and to be avoided at all costs. That's not true per-se. Duplication is only harmful if it makes your code cluttered and thus less readable, or if syncronization becomes an issue - either the risk of getting out of sync or the effort need for changing all places. But synchronization is not an issue if you likely don't change in the future. On the other hand, deduplication always comes at the cost of indirection (how is this description generated?) and stronger coupling (are we sure we always want current_type + f", default: :rc:`{rcparam}`"?) It's always a trade-off; here, I'd claim that clutter and synchronization are not an issue, indirection and coupling are more pressing concerns to me.

(I guess that the rcparam name is quite related, but maybe not related enough to automatically add that?)

I'm pretty sure it's not related enough.

Maybe I wasn't completely clear. I see this as a complement to meet the "yet another thing for new contributors to consider"-argument. This would then only be used if the doc-string does not contain "or None" (i.e., is suitable to start with). It would also add the benefit of a way to directly connect the rcparams to specific setter/kwargs.

For the latter part, one may even consider adding something like:

def kwdoc(text=None, rcparam=None):

where if text is None, the scraper is used and if rcparam is not None, it is added as in my previous example, either to text or the scraped text.

Maybe a bit more time consuming when generating the docs (which indeed is an aspect as well), but will enable to add things in a more flexible manner and can be used for extended things in the future.

def kwdoc(text=None, rcparam=None):

is basically a superset of the API defined here. We can add the rcparam as a shortcut if that's a common enough usecase; which it likely is, but I like to let such API discover itself and not try to design it upfront. I.e. start simple, an when a pattern emerges on use, extract. That makes sure we get exactly what we need. (There's a good talk by Raymond Hettinger propagating this approach).

Does @timhoffm or someone else @oscargus want to move this forward? Moved to draft, but feel free to move back if ready for review...

IMHO this is ready as a minimal version of the feature. The usage is demonstrated in one example. Systematic application should be a follow-up PR, After the fundamental concept is approved here.

Extensions can be added later when needed. This is internal API, so we can always refine or reconsider.

I also rebased and used @jklymak's documentation, with some modifications.

So there is a "new" error in that **kwargs cannot be found, but easily fixed if we do not need a link there...

Anyway, it would be of interest to make some progress on this and decide on which approach to proceed with.

@oscargus I'm happy to approve this if its ready to go?

Is this a proof of concept that should not be merged (as the title suggests) or ready to merge (as the status: needs review label suggests)?

I've mostly been dropping this down my review list because of the title.

I think something like this should be really nice to have. Maybe we should discuss it (once more?) at a dev call before making a decision on which approach.

On the other hand, it is not a big deal to merge this and then decide that we would like a slightly different approach. (The big effort is adding decorators...)

Does this still need discussion?

From my perspective, this is ready to go.

I've rewritten the docstring to hopefully better explain what this does.