Incorrect {@inheritdoc} precedence

[jiripudil]

I've run into this problem with Kdyby/Doctrine:

namespace Doctrine\ORM;
class EntityManager
{
	/**
	 * @return void
	 */
	public function persist($entity) {}
}

namespace Kdyby\Doctrine;
class EntityManager extends \Doctrine\ORM\EntityManager
{
	/**
	 * {@inheritdoc}
	 * @return EntityManager
	 */
	public function persist($entity) {}
}

I'd expect the return type to be Kdyby\Doctrine\EntityManager, however,

/** @var Kdyby\Doctrine\EntityManager $em */
$em->persist($entity)->flush();

reports errors:

Cannot call method flush() on void.                                      
Result of method Kdyby\Doctrine\EntityManager::persist() (void) is used.

(phpstan 0.7.0)

[ondrejmirtes]

I've never seen it used like this. I don't think you have any reason to write {@inheritdoc} in Kdyby\Doctrine\ EntityManager. All instances of {@inheritdoc} I've seen were used exclusively and not in addition to other tags used in the same phpDocs. What do you think @fprochazka?

[fprochazka]

That is something I've no idea where it came from and will be removed.

[jiripudil]

Thanks! I'm closing this then

[sstok]

Please reconsider, this convention is recommended in the current draft of phpdoc https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md#62-using-the-inheritdoc-inline-tag-to-augment-a-description and used in Symfony.

PHP-CS-Fixer actually changes @inheritdoc to {@inheritdoc} (when used for inheriting).

[ondrejmirtes]

@sstok Can you point out what do you mean exactly? {@inheritDoc} is supported by PHPStan. I don't think that the PSR draft means that you can combine {@inheritDoc} with a different @return, only that you can augment a phpDoc description.

[sstok]

Hmm, you seem to be correct 😋 I will fill an issue with the php-cs-fixer instead 👍 Seems this is already reported there PHP-CS-Fixer/PHP-CS-Fixer#2619

[ondrejmirtes]

This now works. Implemented by @alexeyinkin in phpstan/phpstan-src#196. Awesome work!