Problem/Motivation
In
#1906474: [policy adopted] Stop documenting methods with "Overrides β¦" β
we added support for {@inheritdoc} as being the sole thing in a doc block on a method of a class, meaning "Inherit the documentation from a parent class/interface".
This is very useful as it is, but we also have a lot of cases where it would be nice to say "Inherit most of the docs, but override this one part" or "Inherit all of the docs, but add another piece to the end".
And in spite of our coding standards not currently allowing it, Core has many instances of people doing this now.
Survey of how other documentation systems use an "inheritdoc" tag
Proposed resolution
There are two proposals here that people would actually like, for what it would mean if we wanted to have "inheritdoc plus more" in a documentation block, and one more added for contrast:
- It means "Inherit all the documentation and add more to it"
- It means "Inherit all the documentation, but replace parts of the inherited documentation with these replacements"
- We could adopt a system like phpDocumentor where it only means "inherit the long description" (in which case all our existing @inheritdoc blocks would be invalid) or like JavaDoc where it means "inherit the description in context" (ditto).
Note on practicality/feasibility of these proposals:
The "replace" part (option 2), as a practical matter, is not supported by *any* other documentation parser, because it would be very difficult to implement. Actually, even the "inherit and add" part (option 1) is fairly difficult to implement, and would require rearchitecting parts of the API module to take care of it on api.drupal.org, which is probably why no existing documentation system supports it.
The third proposal is feasible to implement, and would be consistent with phpDocumentor. However, as it would invalidate nearly all of our current uses of @inheritdoc, this is not a popular proposal.
Remaining tasks
Everyone likes option 1 above. However, we cannot adopt it if it is not feasible. The API module maintainer says it would be very difficult and require a lot of rearchitecting in order to support this for api.drupal.org. Some IDEs (at least PHPStorm) support option 1.