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?
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.
@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.)
{@inheritdoc} manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/…
{@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).
Following up on comments by @Tgr and @JānisElmeris:
https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc-tags.md#41-making-inheritance-explicit-using-the-inheritdoc-tag says that @inheritDoc is for entirely replacing the child documentation with its parent's documentation; while {@inheritDoc} is conversely for including the parent's documentation (specifically, the main description) at that position in the child documentation.
You should use one or the other in order that human readers can see that documentation is available.
I expect that the letter case for the D is irrelevant, and so the all-lower-case variants are equivalent.
Quoting the current version:
4.1 Making inheritance explicit using the
@inheritDoctagBecause inheritance is implicit it may happen that it is not necessary to include a PHPDoc with a "Structural Element". This can cause confusion as it is now ambiguous whether the PHPDoc was omitted on purpose or whether the author of the code had forgotten to add documentation.
In order to resolve this ambiguity the
@inheritDoctag can be used to indicate that this element will inherit its information from a super-element.
4.2 Using the
{@inheritDoc}inline tag to augment a DescriptionSometimes you want to inherit the Description of a super-element and add your own text with it to provide information specific to your "Structural Element". This MUST be done using the
{@inheritDoc}inline tag.The
{@inheritDoc}inline tag will indicate that at that location the super-element's description MUST be injected or inferred.
Judging from the comments, the URL for this information has changed at least once, so for the sake of persistence the following is section 4 in its entirety:
4. Regarding Inheritance
A PHPDoc that is associated with a "Structural Element" that implements, extends or overrides a "Structural Element" has the ability to inherit parts of information from the PHPDoc associated with the "Structural Element" that is implemented, extended or overridden.
The PHPDoc for every type of "Structural Element" MUST inherit the following parts if that part is absent:
- Summary
- Description and
- A specific subset of Tags:
- @author
- @copyright
- @version
The PHPDoc for each type of "Structural Element" MUST also inherit a specialized subset of tags depending on which "Structural Element" is associated.
If a PHPDoc does not feature a part, such as Summary or Description, that is present in the PHPDoc of a super-element, then that part is always implicitly inherited. The following is a list of all elements whose DocBlocks are able to inherit information from a super-element's DocBlock:
- a Class' or Interface's DocBlock can inherit information from a Class or Interface which it extends.
- a Property's DocBlock can inherit information from a Property with the same name that is declared in a superclass.
- a Method's DocBlock can inherit information from a Method with the same name that is declared in a superclass.
- a Method's DocBlock can inherit information from a Method with the same name that is declared in an implemented interface in the current Class or that is implemented in a superclass.
For example:
Let's assume you have a method \SubClass::myMethod() and its class \SubClass extends the class \SuperClass. And in the class \SuperClass there is a method with the same name (e.g. \SuperClass::myMethod).
If the above applies then the DocBlock of \SubClass::myMethod() will inherit any of the parts mentioned above from the PHPDoc of \SuperClass::myMethod. So if the
@versiontag was not redefined then it is assumed that \SubClass::myMethod() will have the same@versiontag.Inheritance takes place from the root of a class hierarchy graph to its leafs. This means that anything inherited in the bottom of the tree MUST 'bubble' up to the top unless overridden.
4.1. Making inheritance explicit using the
@inheritDoctagBecause inheritance is implicit it may happen that it is not necessary to include a PHPDoc with a "Structural Element". This can cause confusion as it is now ambiguous whether the PHPDoc was omitted on purpose or whether the author of the code had forgotten to add documentation.
In order to resolve this ambiguity the
@inheritDoctag can be used to indicate that this element will inherit its information from a super-element.Example:
/** * This is a summary. */ class SuperClass { } /** * @inheritDoc */ class SubClass extends SuperClass { }In the example above the SubClass' Summary can be considered equal to that of the SuperClass element, which is thus "This is a summary.".
4.2. Using the
{@inheritDoc}inline tag to augment a DescriptionSometimes you want to inherit the Description of a super-element and add your own text with it to provide information specific to your "Structural Element". This MUST be done using the
{@inheritDoc}inline tag.The
{@inheritDoc}inline tag will indicate that at that location the super-element's description MUST be injected or inferred.Example:
/** * This is the Summary for this element. * * {@inheritDoc} * * In addition this description will contain more information that * will provide a detailed piece of information specific to this * element. */In the example above it is indicated that the Description of this PHPDoc is a combination of the Description of the super-element, indicated by the
{@inheritDoc}inline tag, and the subsequent body text.4.3. Element-specific inherited parts
4.3.1. Class Or Interface
In addition to the inherited descriptions and tags as defined in this chapter's root, a class or interface MUST inherit the following tags:
- @package
4.3.2. Function Or Method
In addition to the inherited descriptions and tags as defined in this chapter's root, a function or method in a class or interface MUST inherit the following tags:
- @param
- @return
- @throws
4.3.3. Constant Or Property
In addition to the inherited descriptions and tags as defined in this chapter's root, a constant or property in a class MUST inherit the following tags:
- @var
