Add support for {@inheritdoc}

[patrickkempff]

Many frameworks like symfony use {@inheritdoc} to inherit documentation for a method of a class that implements an interface.

Example (simplified):

<?php

/**
 * Command.
 *
 * @author Fabien Potencier <[email protected]>
 */
abstract class ContainerAwareCommand extends Command implements ContainerAwareInterface
{

    /**
     * {@inheritdoc}
     */
    public function setContainer(ContainerInterface $container = null)
    {
        $this->container = $container;
    }


}

This class implements ContainerAwareInterface

interface ContainerAwareInterface
{
    /**
     * Sets the Container.
     *
     * @param ContainerInterface|null $container A ContainerInterface instance or null
     *
     * @api
     */
    public function setContainer(ContainerInterface $container = null);
}

I get the following result:

[ghost]

Hello

inheritDoc is mostly implementend in pull request #74 . Note, however, that the example you gave does not correctly utilize the inheritDoc tag; it is only intended for the (long) description and does not inherit anything else, such as the parameter block or return statement [1].

However, the usage you're showing here is a very valid use case (and I have in fact long done the same). Sadly, there is no current valid way to indicate that a docblock should be entirely inherited, except for omitting or copying it entirely, which in turn makes other developers think that you forgot the docblock or making you copy paste docblocks for minor updates. A third alternative is to use some kind of different comment syntax above the method, to indicate it was not forgotten, that IDE's or documentation generators will not trip over.

I should also mention that phpDocumentor is not really a standard, just an implementation (IDE's or other tools might behave differently). Sadly there is no current documentation standard. This situation will hopefully be resolved with PSR-5 (which is currently still in draft) [2].

[1] http://phpdoc.org/docs/latest/guides/inheritance.html
[2] php-fig/fig-standards#169

[Peekmo]

Hello,

I think that we could copy/past all the docblock if the only comment for a method is {@inheritdoc}
What do you think about it @hotoiledgoblinsack ?

Peekmo

[ghost]

I was thinking the same thing, but will we do the same if some other framework (e.g. Laravel or Zend) decides to take another approach? I guess it's a question of whether or not you want to support workarounds/hacks for specific frameworks (Symfony in this case). For me, I can argue for and live with both opinions. On one side, a lot of people use Symfony and can benefit from this, but on the other hand, the 'issue' is in the Symfony code (which in turn probably only does this because there is no PHP standard for documentation).

PS: Note that Symfony uses inheritdoc with a lowercase D whilst the official syntax is inheritDoc, that might make it easier to differentiate between the two.

[Peekmo]

Laravel uses inheritdoc too (I don't know for Zend).

Anyway, some editors use their own annotation to describe a full doc block inheritance, so, I think that for this plugin, using the already widely use {@inheritDoc} (or {@inheritdoc} the character case should not matter for this, there's also an uppercase D in symfony2 sometimes) is probably a good thing.

[ghost]

Ok, in that case, I would suggest using a specific implementation as base and adding exceptions on top of that (such as this inheritdoc usage). Probably the best implementation to stick to for now seems to be phpDocumentor as one of its developers is also the one managing the PSR-5 standard pull request for PHP and PSR-5 used phpDocumentor's implementation as its starting point. This way there will be less code to change when PSR-5 is officially standardized (and most of our docblock parsing code already follows it). IDE's and other tools will then (hopefully) slowly move to PSR-5 as well.

I'd also suggest reading inheritDoc and inheritdoc for this ticket, but I wouldn't go as far as making everything case insensitive in the docblock parser; it's fair that Symfony uses inheritDoc for full docblock inheritance as there are few alternatives, but using both casings on their side seems to be more of an inconsistency in their codebase ;-).

[ghost]

@patrickkempff The current v0.11.0 includes support for Symfony's (mis)use of the inheritDoc tag (both with lowercase and uppercase D), is this sufficient for you?

[patrickkempff]

sorry for the late reply but this is more than sufficient for me. thank you @hotoiledgoblinsack and @Peekmo