Support {@inheritdoc}

[piotr-cz]

Let's consider allowing the {@inheritdoc} tag.

This really helps when extending classes, you don't have to rewrite whole docblock and keep it up to date with docblock changes in base class.

Important bonus is that one can easily see that the property has a parent.

At this moment php code sniffer complains like:

50 | ERROR | Doc comment for "$form" missing
52 | ERROR | Missing @return tag in function comment

This tag is being widely used in projects like Symfony and Drupal.

Usage

class A
{
    /**
     * Foo method
     *
     * @param   array  $bar  Bar
     *
     * @return  void
     */
    public function foo(array $bar)
    {
    }
}

class B extends A
{
    /**
     * {@inheritDoc}
     */
    public function foo(array $bar)
    {
    }
}

References

• javadoc: {@inheritdoc}
• phpDocumentor: {@inheritdoc}

[mbabker]

I wouldn't mind it. I'd also suggest following the PSR proposal and https://github.com/phpDocumentor/fig-standards/issues/37 specifically as a tag without the brackets may be introduced. And FWIW, in some code I'm trying out locally, I started using that tag in place of the "proper" doc block.

While I'm thinking about it, if there are any issues with our sniffer not accepting something in the PSR, as it is defined and ratified, we should adjust our rules to adapt, to include potentially throwing warnings on deprecated tags.

On Monday, December 23, 2013, Piotr wrote:

Let's consider allowing the {@inheritdoc} tag.

This really helps when extending classes, you don't have to rewrite whole docblock and keep it up to date with docblock changes in base class.

Important bonus is that one can easily see that the method has a parent.

At this moment php code sniffer complains like:

50 | ERROR | Doc comment for "$form" missing 52 | ERROR | Missing @return tag in function comment

This tag is being widely used in projects like Symfony and Drupal. Usage

class A{ /** * Foo method * * @param array $bar Bar * * @return void / public function foo(array $bar) { }} class B extends A{ /* * {@inheritdoc} */ public function foo(array $bar) { }}

References

• javadoc: {@inheritdoc}http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/javadoc.html#@inheritDoc
• phpDocumentor: {@inheritdoc}http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlineinheritdoc.pkg.html

— Reply to this email directly or view it on GitHubhttps://github.com/joomla/coding-standards/issues/50 .

[dongilbert]

The PSR isn't yet ratified, it's still in progress.

[piotr-cz]

So I'm actually referring to a @inheritDoc tag, that's not yet part of phpDocumentor.

{@inheritdoc} is used just for descriptions or @param's text values.

[mbabker]

Got that, just saying keep an eye on it as it works through the system, that's all.

On Mon, Dec 23, 2013 at 11:40 AM, Don Gilbert [email protected]:

The PSR isn't yet ratified, it's still in progress.

— Reply to this email directly or view it on GitHubhttps://github.com/joomla/coding-standards/issues/50#issuecomment-31132581 .

[piotr-cz]

You, but I didn't :smile: Thanks for that link, I didn't know I've been using this tag wrong way all the time.

[eddieajau]

I personally don't like the inheritdoc tag because when I'm inspecting the code I have to work up the inheritance chain to find the documentation. It's not so bad once you get to know the code but I find it annoying if I'm trying to learn the API, not to mention evaluate a pull request. This is something that frustrates me when I look at other frameworks.

Regards, Andrew Eddie http://learn.theartofjoomla.com - free tutorials and videos on Joomla development

[piotr-cz]

@eddieajau I didn't think of this. You are right, this tag makes it harder to learn the API, but easier when working with something you already know. Does anybody know what is the support in IDEs? If one could see the inherited docblock, I think we could start using it but if not, let's not use it ATM

[piotr-cz]

New resources to consider:

• reference to phpDocumentor manual: Basic Syntax > Inheritance
• PSR-5: PHPDoc Standard (DRAFT, WIP)

[asika32764]

For my experience, PHPStorm cannot show any information of {@inheritDoc}, I have to trace the parent to see docblock.

I'm agree with @eddieajau, I also don't like this tag. It's my personal opinion.

But I think we can wait for PSR-5

[andkirby]

After CodeSniffer/Standards/PEAR/Sniffs/Commenting/FunctionCommentSniff.php:129 We may put:

        foreach ($tokens[$commentStart]['comment_tags'] as $tag) {
            if (strtolower($tokens[$tag]['content']) == '@inheritdoc') {
                $isSpecialMethod = true;
            }
            [...]
        }

It will work. Perhaps this validation is needed to be replaced with customized one.

[RusAlex]

Any progress on this ?

[laoneo]

For example Eclipse does support it and I guess PHPStorm does as well. It makes no sense to copy doc blocks from the base class. If that doc block changes all the subclasses do need to be updated.

[elkuku]

I also don't like it personally and would go with @eddieajau on this.

On the other hand I believe that the sniffer should "allow" it so extension devs may use it as they wish. The code proposed by @andkirby looks good. Maybe a PR would be accepted?

[piotr-cz]

Apparently this tag is being supported in PHPStorm since v6 (I can't confirm as I'm not using it).

Joomla is the only framework I've used that doesn't implement it.