Allow {@inheritdoc} and additional documentation

Created on 14 May 2013, almost 12 years ago
Updated 11 December 2024, 3 months ago

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:

  1. It means "Inherit all the documentation and add more to it"
  2. It means "Inherit all the documentation, but replace parts of the inherited documentation with these replacements"
  3. 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.

πŸ“Œ Task
Status

Active

Component

Coding Standards

Created by

πŸ‡¨πŸ‡­Switzerland ParisLiakos

Live updates comments and jobs are added and updated live.
  • Coding standards

    It involves compliance with, or the content of coding standards. Requires broad community agreement.

Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

  • πŸ‡ΊπŸ‡ΈUnited States kentr Durango, CO

    phpDocumentor support is similar to #45, also overriding parameter & return declarations. The layout is similar to the VS Code Intelephense version.

    This code:

    class A {
        /**
         * Parent method summary.
         *
         * Parent method long description.
         *
         * @param bool $input The input.
         *
         * @return bool
         */
        public function method($input = TRUE) {
            return $input;
        }
    }
    
    class B extends A {
        /**
         * {@inheritDoc}
         *
         * Child method additonal details.
         *
         * @param string $input The input.
         *
         * @return string
         */
        public function method($input = 'default') {
            return $input;
        }
    }
    

    Outputs:

  • πŸ‡ΊπŸ‡ΈUnited States kentr Durango, CO
  • πŸ‡³πŸ‡ΏNew Zealand quietone

    Converting to new issue template

  • πŸ‡³πŸ‡ΏNew Zealand quietone
Production build 0.71.5 2024