Redundant documentation in interface+implementation, or errors

[fi5er]

With an interface defining a method and a class implementing it, both must have nearly identical doc blocks. If the implementation has no doc block on the method, or it's missing the summary or @param tags, phpDocumentor2 sees that as an error (in the CLI, with a nasty looking red background, and on the "Errors" report page).

Errors notwithstanding, the doc block from the interface does show up in the generated documentation for the implementation, as it should. As far as I can see, there is no way to silence this type of error.

Is my understanding correct that I have to choose between maintaining two largely identical copies of a method doc block, or living with lots of error messages? When there are lots of non-critical warnings, they tend to get ignored, and any legitimate warning will probably go unnoticed.

/** The IThing interface summary. */
interface IThing
{
    /**
     * Method summary (in interface).
     *
     * Method description (in interface).
     *
     * @param  string  $foo  a parameter
     * @return  string  some string
     */
    public function methodOne($foo);
}

/** The Thing class summary. */
final class Thing implements IThing
{
    // need at least summary + @param here
    public function methodOne($foo) { /*...*/ }
}

The same basic question also applies to inherited properties and methods.

[jaapio]

With @inheritdoc you can import the summary. But there is no way to copy all tags. We will have a look if and how we can achieve this.

ping @waltertamboer

[waltertamboer]

I am struggling with the same problem. Since all methods should have a docblock, it would be nice to simply have an "@inherit" annotation that inherits the docblock of the parent. I'm not sure if this is considered in PSR-5?

In PSR-5 there is a part about inheritance but it seems a bit too unclear to me. I'm not sure if @inheritDoc inherits only the summary (because {@inheritDoc} does) or if it inherits the other tags as well?

https://github.com/php-fig/fig-standards/pull/169/files

[jaapio]

I checked that for you. But I can't find anything in de code of phpdocumentor about the @inheritDoc tag. So I'm not sure how this works. {@inheritDoc} is implemented.

Good to know is that there is a difference in the implementation. Between summary and description. Summary is concidered to be a single line. So when you place {@inheritDoc} it will just get that line. In the description the tag is replaced with the description of the parent element.

@inheritDoc takes both summary and description.

@inherit sounds like a good idea. But here will be situations where you might need to modify some of the tags or add others. So we will need to define how this should work. For all supported tags.

[mvriel]

For PSR-5 we have had discussions with the maintainers of Doctrine on how to approach this issue.

Historically {@inheritDoc} could only be used in the description and would import the parent description into that location. Summaries don't support the braced inline tag style and if a summary was omitted then the use of {@inheritDoc} was considered to be invalid according to the specs of phpDocumentor.

Since phpDocumentor 1 came out Doctrine and Symfony have adopted the use of {@inheritDoc} to mean 'inherit everything from the parent element' when used on its own in a DocBlock.

Like this:

/**
 * {@inheritDoc}
 */

With phpDocumentor 2 we have adopted that behaviour to prevent confusion with users that produced that style of documentation.

When I wrote PSR-5 I had discussions with Ocramius if we could somehow 'rectify' the inconsistency of {@inheritDoc}'s usage as the body of the DocBlock and we came up with the tag @inheritDoc.

Tags are allowed to be used without a Summary and Description according to the PHPDoc syntax and @inheritDoc would then mean 'apply inheritance as if no DocBlock is present'.