[Coding Standards] inheritdoc PHPDoc tag must always be inline.

[soullivaneuh]

A Symfony PHP-CS-Fixer fixer named phpdoc_inline_tag exists:

Fix PHPDoc inline tags, make inheritdoc always inline.

But I saw no indication about this rules on the coding standards documentation.

This should be added IMHO to avoid confusion between bundles developer and issue opening of this kind: sonata-project/dev-kit#180 😉

[ju1ius]

For reference, an excerpt of the inheritdoc tag documentation:

Currently some applications have DocBlocks containing just the {@inheritDoc} inline tag to indicate that their complete contents should be inherited. This usage breaks with the PHPDoc Standard as summaries cannot contain inline tags and inheritance is automatic; you do not need to define a special tag for it.

However, it does make clear that an element has been explicitly documented (and thus not forgotten). As such we are working to include a new (normal) tag in the PHPDoc Standard @inheritDoc that will serve that purpose.

[soullivaneuh]

@ju1ius I don't think they follow this rule.

[ju1ius]

@soullivaneuh which is precisely why I posted the documentation.

[soullivaneuh]

And I think this should be discussed on another issue too. :-)

This issue is about adding missing documentation for the actual rule.

[ju1ius]

Ok didn't get that 😉

[javiereguiluz]

@soullivaneuh are you saying that we should write inheritdoc like this?

/** {@inheritdoc} */
public function __construct($dummy) {
    // ...
}

instead of this?

/**
 * {@inheritdoc}
 */
public function __construct($dummy) {
    // ...
}

Because I can't find a single use of the first notation in the Symfony code. It's always like the second example.

[javiereguiluz]

Closing this as fixed because the docs already say Inline the @inheritdoc tag. See https://symfony.com/doc/current/contributing/code/standards.html#documentation

However, I think this is wrong and I've opened #9211 to change this. Thanks!

[devnix]

Don't know if it has changed but the documentation clearly says

Don't inline PHPDoc blocks, even when they contain just one tag (e.g. don't put /** {@inheritdoc} */ in a single line);