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. (since 916f4ff) interpd also always corrects indentation. Therefore dedent_interpd and interpd are equivalent and we should remove dedent_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 is args or kwargs (i.e. a tuple or a dict). This is ok for formatting (inspect.cleandoc(func.__doc__) % self.params). But Substitution has an update() method, which only works when params 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 it https://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 after MNT: 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.