Correct syntax for inheritDoc in phpDocumentor

Question

What is the correct syntax for @inheritDoc in phpDocumentor if I just want to inherit all of the documentation from parent? Maybe more than one syntax is correct?

1. @inheritDoc
2. {@inheritDoc}
3. @inheritdoc
4. {@inheritdoc}

The documentation is pretty vague I think. PhpStorm seems to support all of them but maybe I'll have trouble generating the docs with some of the syntax?

Solution 1

A child element should be automatically inheriting pretty much everything from its parent docblock without needing this tag. Otherwise, all your implementation methods would have to be documented all over again without gaining anything by the original interface's documentation.

Simply, an inherited element without a docblock should automatically inherit everything from its parent's docblock.

The @inheritdoc tag's sole purpose is to help you import one thing from the parent docblock -- that parent's Long Description. The only reason the child should not already have this available is if the child went ahead and had its own docblock. Now, the child should still be inheriting nearly everything from its parent docblock without having to duplicate it... except the parent's Long Description. If the child docblock chose to have its own docblock for some reason, and you still want to inherit the parent's Long Description, then where you put @inheritdoc in the child docblock determines where that parent Long Description appears. Thus, the child can have its own Short Description and Long Description, and still also include its parent's Long Description in a specified spot in relation to the child Long Description. This is the sole reason this tag was ever born :-)

With regard to IDE autocompletion, I can't say that I've seen consistent behavior across IDEs when it comes to this tag. Further, I've seen projects where the assumption is made that this tag is the reason that inherited information from parent docblocks even happens.

Solution 2

I know nothing about IDE support but the documentation spells it as {@inheritDoc}.

Comments

[John Pancoast]

I think the answer is mostly there but you should clarify that you mean {@inheritDoc}. The braces clarify that it's inline and this only brings in the long desc like you said. See the note here about {@inheritdoc}, it's misuse, and the new @inheritDoc tag on its way phpdoc.org/docs/latest/guides/….

[GusDeCooL]

the documentation also spell it as {@inheritdoc} manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/…

[Tgr]

@inheritDoc is handy in legacy codebases to tell readers that the documentation is missing intentionally. Documentation generators don't need that but humans looking at the code in an editor / on Github do. (This is apparently called out explicitly in the draft standard as well.)

[jinyong lee]

In addition to docs.phpdoc.org documentation spelling it as {@inheritDoc}, it addresses the usage of this tag for explicitly replacing all contents of the DocBlock with that of the parent/interface (see the red "important" paragraph), and distinguishes between the original inline {@inheritDoc} tag which includes the description of the parent, and a new/potential @inheritDoc tag, that replaces the whole content (and which is already being used in that way by some clients).