Correct syntax for inheritDoc in phpDocumentor
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?
@inheritDoc{@inheritDoc}@inheritdoc{@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?
Answer
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.