Admittedly, I also don't have a full overview on our substitution mechanims (but possibly that's part of the problem here). I have the feeling that the description here only targets part of our machinery and it is still not clear what exactly we have and for which
cases it should be used.

We have

• _docstring.copy: A decorator to copy a docstring from another function.
  Assumed use cases::
  • Re-expose the same docstring on a different function (used for pyplot wrappers)
  • copy "docstring templates" (see.Substitution)
• Substitution: A decorator for %-substition of docstrings.
  Assumed use cases:
  • Inject runtime information into docstrings (e.g.RcParams)
  • Inject the same code into multiple docstrings to prevent repetition (e.g. _RECTANGLESELECTOR_PARAMETERS_DOCSTRING)
  • Allow variations of a reused docstring (e.g. through@_docstring.copy)
• _ArtistPropertiesSubstitution (instantiated as_docsting.dedent_interpd /_docstring.interpd)
  Assumed use cases:
  • Register for named placeholders, e.g.%(cmap_doc)s - add entries via @_docstring.interpd.update()`
  • Use as decorator for
    • Resolving the registered named placeholders in associated docstrings
    • Automatic resolution of%(classname:kwdoc)s

Notes:

1. (since916f4ff)interpd also always corrects indentation. Thereforededent_interpd andinterpd are equivalent and we should removededent_interpd.
2. I've an issue with naming. "Interpolation" seems like a slang term. What we do is inject content / substitute placeholders / technically perform string formatting for a predefined set of names. I believe we should make this more clear in our naming.
3. There are some quirks in the class design, e.g.Substitution.params isargs or kwargs (i.e. a tuple or a dict). This is ok for formatting (inspect.cleandoc(func.__doc__) % self.params). ButSubstitution has anupdate() method, which only works whenparams is a dict.

I believe we first have to clean up and sort out what we actually want to do with these helpers before we can cleanly document their usage.

I've an issue with naming. "Interpolation" seems like a slang term. What we do is inject content / substitute placeholders / technically perform string formatting for a predefined set of names. I believe we should make this more clear in our naming.

It is a defined term for ithttps://en.wikipedia.org/wiki/String_interpolation (though generally only applying immediately to literals, I think, it could be argued as similar enough.)

If we want to cling to "interpolation", we should use the full technical "string interpolation" (or "docstring interpolation" if you want). "interpolation" by itself is much more associated with mathematics, which would be confusing.

I was gonna just change it up to something like "Create reusable docstrings" - focus on purpose rather than mechanism 🤷‍♀️

I like "Reuse docstrings". It has more focus on the act of reusing compared to the creation.

This section could contain the existing "Inherit docstrings" as a subsection. It should eventually mention all_docstring methods:

• _docstring.copy
• _docstring.Substitution (or afterMNT: Cleanup docstring substitution mechanisms #28795_docstring.format)
• _docstring.interpd

But as you say, structure by purpose rather than mechanics. I believe the "Assumed use cases" from#28746 (comment) could be a guideline for purposes. I think we currently do:

• Inject runtime information into docstrings:_docstring.format
• Use the same (template) docstring for multiple functions:_docstring.copy. Variations can be added on top via _docstring.format
• Use the same pre-defined fragment inside multiple docstrings:_docstring.interpd

That said, I'm not quite clear whether we need both_docstring.format and_docstring.interpd. The difference being that format gives the content to insert explicitly, whereas interpd takes it by name from a registry.