43

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?

Borek Bernard
  • 50,745
  • 59
  • 165
  • 240

2 Answers2

63

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.

ashnazg
  • 6,558
  • 2
  • 32
  • 39
  • 10
    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 https://www.phpdoc.org/docs/latest/guides/inheritance.html#the-inheritdoc-tag. – John Pancoast Apr 20 '16 at 18:14
  • `@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](https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md#61-making-inheritance-explicit-using-the-inheritdoc-tag) in the draft standard as well.) – Tgr Sep 08 '17 at 00:53
5

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

Fahmi
  • 2,607
  • 1
  • 20
  • 15
  • 2
    the documentation also spell it as `{@inheritdoc}` https://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlineinheritdoc.pkg.html – GusDeCooL Sep 05 '17 at 00:03
  • 1
    In addition to [docs.phpdoc.org](https://docs.phpdoc.org/guides/inheritance.html#the-inheritdoc-tag) 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). – Jānis Elmeris Nov 30 '17 at 10:52