Don't suggest "Generate @inheritDoc" for methods when parameter list differs

[Gert-dev]

You can't inherit the entire documentation from a parent method if its parameter list is different, as the documentation doesn't apply.

[twifty]

I know @inheritdoc is a very gray area, but I've always been under the impression that it pulls in the long description from the parent doc. Most environments I've used pull the short description, long description and parameter list from the parent, but allow overriding each in the child. So a docblock like:

/**
 * @inheritDoc
 *
 * @param Foo bar
 */

would inherit the short and long descriptions and replace the parameter list in the parent.

In most cases, when overriding a method, the intention of the method (it's short/long description) doesn't change, even when there are extra parameters.

[Gert-dev]

It depends; I think you're referring to {@inheritDoc} (note that actually no version with a small D "exists"). This is a different tag from @inheritDoc without the curly braces. I've written a bit about it in the past, and the phpDocumentor documentation may also be relevant.

The major problem is that currently there is no standard around docblocks, just some implementations. To make matters worse, some code bases (such as Symfony) have begun plopping {@inheritdoc} (which is both incorrectly spelled and the wrong tag for it) all over the place to signify complete inheritance of the docblock. The broken syntax, as mentioned in the article on the wiki, is still supported though, but I advise against it as there is a clear difference in intent between both.

As such, the @inheritDoc tag seems to only be allowed alone in a docblock, there may not be any additional tags supplied. If you want to inherit the long description (and only the long description, the summary is not included), you can use {@inheritDoc} instead, but you'll need to supply all the parameters, throws, and other information as well.

To make matters worse, the PSR-5 did say that @param tags, the summary, description, and so on must be inherited implicitly, but it does not clarify about how the @inheritDoc tag fits into that (it only lists examples where @inheritDoc is used alone). So, in theory, you could take that to assume you could just use a docblock such as:

class A
{
    /** Some summary */
    public function foo() {}
}

class B
{
    // The summary is inherited here.
    /** 
     * @param string $additionalParam
     */
    public function foo($additionalParam) {}
}

Unfortunately the PSR-5 was abandoned, though, so we're back to square one. In the meantime, PHPStan - which is a great initiative in itself - has created another variant by introducing intersection types inside docblocks (which no other tool I've seen supports) as well as generic syntax (PhpStorm supports that too), which may conflict with the actual generics syntax if it is ever added to core PHP. Of course these projects are only adding what they feel is necessary for their own operation, but it is making it extremely hard to write docblocks that work harmoniously with all tools.

I've thought about taking over the standard effort, but this project is already massive in scope for one guy, and that is one additional task I do not wish to tackle :/.