Yii2: @inheritdoc should be {@inheritdoc}

[michaelarnauts]

According to the documentation of phpdoc, the @inheritdoc tag to indicate that the function documentation should be copied from the parent function should be written as {@inheritdoc}.

Currently, @inheritdoc is used everywhere in the code of Yii2.

The next version of Netbeans should be able to process these according to this page.

[Faryshta]

i think the use case there is distinct.

/**
 * @inheritdoc
 */
public function method();

will copy the long description, and other tags like params, return, etc.

/**
 * {@inheritdoc}
 * @return string
 */
public function method();

Will copy ONLY the long description, not the rest of the tags which have to be asigned again.

[cebe]

The problem with this is, that there is no real spec of PHPDoc (yet) and at the time when the yii2-apidoc tool has been implemented the page you linked also contained an @inheritdoc tag that was described to work similar to what is implemented now. It is actually still there in the PSR proposal: https://github.com/phpDocumentor/fig-standards/blob/b994d853b8ba33bd4bfb00e53cc268d57a5d1e7b/proposed/phpdoc.md#61-making-inheritance-explicit-using-the-inheritdoc-tag so it is hard to say which notation is correct. Because our usage of @inheritdoc is meant to inherit everything and not just description, it is the correct tag to use imo.

[samdark]

IDEs are OK with what's used currently.

[rob006]

IDEs are OK with what's used currently.

Well, this is not true. I'm testing NetBeans 8.2-RC now and only {@inheritdoc} works properly. With @inheritdoc it drops method description and actually works like without any inheritdoc tag.

[MaksimKiselev]

Для всех методов где есть тег @inheritdoc просто добавить {}?

[cebe]

@MKiselev no, APIdoc tool must be adjusted, see https://github.com/yiisoft/yii2/issues/11635#issuecomment-221995372

[MaksimKiselev]

@cebe yep, I was read this PSR.

[cebe]

As long as there is no spec to follow I do not think there is anything we can do about this issue.
There is a significant differentce between @inheritdoc and {@inheritdoc}. @inheritdoc will inherit all tags, {@inheritdoc} will only inherit description. We can not easily change Yii code to use {@inheritdoc}.

[rob006]

@cebe "all tags" are inherited by default, so {@inheritdoc} and @inheritdoc would work exactly the same in 99% cases. And remaining 1% contains mostly situations when @inheritdoc is used as inline tag: https://github.com/yiisoft/yii2/blob/master/framework/db/Query.php#L558-L574 . So basically Yii 2 already (incorrectly) uses @inheritdoc as inline tag.

But the main problem with @inheritdoc is that nobody (except Yii 2) using it - everyone sticks to {@inheritdoc}. So @inheritdoc will always have worse support than {@inheritdoc}. We already have great phpdoc with broken links because nobody supports custom [[]] syntax, do we really need another Yii-specific syntax in phpdoc?

[sergeymakinen]

I tend to agree with @rob006.

/**
 * @inheritDoc
 */

blocks should be removed at all as they simply don't make any sense.

Only inline {@inheritDoc} should be left when they're needed.

[cebe]

What exactly is not working with current Yii PHPdoc?

[rob006]

Links to classes/methods/properties. Yii 2 uses [[]] syntax which is supported only by yii2-apidoc (note that [[select]] is not parsed here):

Yii 1.1 uses standard {@link} which works perfectly fine in PhpStorm:

[klimov-paul]

How does usage of {@link} is related to @inheritdoc topic?
If you are concern about it - you should open a separated issue.

[rob006]

@klimov-paul {@link} is only another example of yii-specific syntax in phpdoc (after using @inheritdoc instead of {@inheritdoc}). But you're right, it should have another issue.

[bizley]

I'll just drop the link to phpDocumentor 2 mentioning the @inheritdoc.

[sergeymakinen]

TBH, this issue mostly describes problems with a documentation parsing in IDEs. In a long term, I think it's easier for PhpStorm to support @inheritDoc.

[cebe]

we're going to make a standard and then follow it ;) https://twitter.com/cebe_cc/status/884929923294650368

[rob006]

Personally I don't see any sense in existing of @inheritdoc. It was created only because someone see problem in docblock with {@inheritdoc} only. So now we have special non-inline tag which can be used only in one scenario and result is exactly the same as with inline tag. It adds only unnecessary complexity, nothing more.

[jblac]

What we've noticed, is phpDocumentor generates errors with @inheritdoc but with {@inheritdoc} it does not. Take it for what it's worth -- I've started having my team use the latter option because I don't like my error report being above 0... but, i'm anal that way.

[klimov-paul]

See https://github.com/yiisoft/yii2-apidoc/issues/160

[samdark]

Summary of current IDE support

Block-level @inheritdoc

Eclipse PDT

• @inheritdoc doesn't work.

Netbeans 8.2

• @inheritdoc doesn't work.

PhpStorm

• @inheritDoc works the same as @inheritdoc.
• If there's only @inheritdoc, both description and meta-tags are inherited.
• If there are description and @inheritdoc, it overrides description but inherits meta-tags.
• @since isn't inherited.
• If there are @inheritdoc and meta-tags, it inherits description and adds new meta-tags to the ones from parent class.
  Weird thing is that same-named @param tags are duplicated:

Base

/**     
 * @param int $a
 * @param int $b
 */

and

/**
 * @inheritdoc
 * @param string $b
 * @param int $a
 */

gives:

string $b
int $a
int $a
int $b

Inline {@inheritdoc}

Eclipse PDT

• {@inheritdoc} doesn't work.

NetBeans 8.2

• {@inheritDoc} works for classes, @since is inherited.
• {@inheritDoc} does not work for methods.

PhpStorm

• {@inheritDoc} works like block-level @inheritdoc while {@inheritdoc} (lowercase) works as expected replacing only
  the token with inehrited description.
• If there's only {@inheritdoc}, both description and meta-tags are inherited.
• @since isn't inherited.

• If there is description and {@inheritdoc} in it, then {@inheritdoc} is replaced with inherited description. Meta-tags
  are inherited.

• If there are {@inheritdoc} and meta-tags, it behaves by replacing {@inheritdoc} with description and weird-merging
  meta-tags.

[samdark]

That basically means that there's no sense to switch to {@inheritdoc} for all doc comments but supporting it is nice to have since there's PSR for it and it may be used in projects.

[klimov-paul]

So we consider @rob006's screenshots to be forged in Photoshop or something?

Looks like there are 2 researches here with quite an opposite results, so it is hard to determine, who speaks the truth.

[klimov-paul]

it is nice to have since there's PSR for it and it may be used in projects.

PHPDocumentor project uses {@inheritdoc} tag with brackets. See:
https://github.com/phpDocumentor/Reflection/blob/develop/src/phpDocumentor/Reflection/Php/Argument.php#L63-L65
https://github.com/phpDocumentor/ReflectionDocBlock/blob/3.3.2/src/DocBlock/Tags/PropertyRead.php#L50-L53

This project is the closest thing to be a standard about PHPDoc at the present state.
We use thier libraries to create our own APIDoc at yii2-apidoc.

[samdark]

Hmm... let me reinstall NetBeans and try again. I've tried by mouse + CTRL over class name (works) and same over method name (displays @inheritdoc).

[samdark]

NetBeans 8.2 release:

[samdark]

@rob006
inheritdoc_playground.zip

[rob006]

@samdark {@inheritdoc} should go on its own line. Using it as this is {@inheritdoc} string does not make any sense.

[klimov-paul]

@samdark, you are mixing different things here.
The example you provide here is doomed to fail and does not relates to this issue.

PHPDoc has a specific demand on formatting: description plain text goes first, then tags @param, @return and so on.

In your example you attempt to forge method PHPDoc to be following:

/**
 * This is
 * Parent description
 * @param int $var
 * @return int
 * string
 */

which is obviously incorrect.

[klimov-paul]

The question here is whether IDE picks up parent description from @inheritdoc (plain) as well as from {@inheritdoc} (with brackets) correctly or not.

E.g. which has better support:

this?

/**
 * @inheritdoc
 */
public function foo() {..}

/**
 * @inheritdoc
 * @return Override
 */
public function foo() {..}

/**
 * @inheritdoc
 * @param Override $var
 */
public function foo($var) {..}

or this?

/**
 * {@inheritdoc}
 */
public function foo() {..}

/**
 * {@inheritdoc}
 * @return Override
 */
public function foo() {..}

/**
 * {@inheritdoc}
 * @param Override $var
 */
public function foo($var) {..}

[samdark]

OK. Netbeans supports plain {@inheritdoc} well. Also checked phpdocumentor code. It doesn't support @inheritdoc w/o { and } at all so yeah, it makes sense to have it.

@rob006, @klimov-paul my example makes sense according to phpdocumenor docs:

• http://docs.phpdoc.org/guides/inheritance.html
• https://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlineinheritdoc.pkg.html

But indeed, that doesn't matter.

[samdark]

So I'm all for {@inheritdoc} w/o any extra strings or property overrides. It has the best support among phpdocumentor, phpstorm and netbeans.

[klimov-paul]

OK, since yii2-apidoc now supports brackets for 'inheritdoc', I will update the source code in the next few days.

[cebe]

Does {@inheritdoc} pick up the short or long description or both?

/**
 * This is the short description.
 *
 * This is the long description...
 */

[samdark]

Both.

[cebe]

here is an example, where at the position of @inheritdoc only the long description of the parent method should be inserted: https://github.com/yiisoft/yii2/blob/248415422f85dee805ff4cfe3b0a666edc5cdc2a/framework/db/Query.php#L695

[rob006]

@cebe There is no real standard for this, so every IDE/tool behaves differently. AFAIK, according to phpDocumentor docs, summary and description inherits separately, so in this Query example only summary should be inserted in the place of {@inheritdoc}.

BTW: I've made some research some time ago. Not sure if it is still valid, but prepare for brainfuck: https://netbeans.org/bugzilla/show_bug.cgi?id=269107#c8 :D

[klimov-paul]

Resolved by commit 65f6b59b35cc63aee7f16a64aeafcec11a8dba39