Phpstan: inheritdoc and return $this problematic

[dereuromark]

Method TestFixture::setTableSchema() should return $this(TableSchemaAwareInterface) but returns $this(TestFixture).

https://phpstan.org/r/8dc3f564-0a64-4a61-9170-e346353a7c30

The interface is not an object ($this is not possible), on the implemented actual object $this then inherited becomes the object instance and therefore the error here is wrong.
It returns the object, not the interface.

I guess {@inheritDoc} here is the problem as it works with @inheritDoc.

Similar, but somewhat different from https://github.com/phpstan/phpstan/issues/12 and https://github.com/phpstan/phpstan/issues/1332

[Jean85]

I'm having the same issue in https://github.com/getsentry/sentry-php/pull/728#issuecomment-448157735

This is basically an issue every time that you define an interface that has fluent interface.

[robbieaverill]

I guess {@inheritDoc} here is the problem as it works with @inheritDoc.

Actually, the former is the same (to phpstan 0.11.4) as not having a docblock at all. PhpDocBlock has a regex which doesn't match @inheritDoc without braces at all, ~which is a bug on its own.~

_Edit:_ actually, PSR-19 doesn't mention anything about omitting braces, so I suppose that we can assume it requires them. In that case @inheritdoc's presence in a docblock overrides the parent's docblock which is why you don't see any errors in phpstan while using it.

_Edit again:_ my mistake, I missed the obvious difference above that: https://github.com/php-fig/fig-standards/blob/5a5005d/proposed/phpdoc-tags.md#41-making-inheritance-explicit-using-the-inheritdoc-tag

[ondrejmirtes]

Fixed: https://github.com/phpstan/phpstan/commit/093b48fc451641892719e5b65f3fa4b7d0f4320a