Always @inheritdoc

[iluuu1994]

class Foo {
	/** @return void */
	public function a() {}

	/** @return void */
	public function b() {}
}

class Bar extends Foo {
	/** Some comment */
	public function a() {}

	public function b() {}
}

https://phpstan.org/r/7058069c-167f-4cf4-9f27-f6b2e865dd7d

Method Bar::a() has no return typehint specified.

Psalm inherits the phpDoc types even if no @inheritdoc is specified. Every IDE does this. I think PHPStan should do the same. What do you think?

[dktapps]

#2898

[ondrejmirtes]

Yes, I'm starting to think it'd be useful :) The main challenge is doing this when a phpDoc should be partially merged with the parent, e.g.

class Foo {
	/**
	 * @param A $a
         * @param B $b
         * @return X
	 */
	public function a($a, $b) {}

}

class Bar extends Foo {
	/**
	 * @param Y $a
         * @return Z
	 */
	public function a($a, $b // still B) {}

}

The problem is that each tag needs its own merging logic. @params should override themselves with the child definitions. With @return the child always wins, @throws from parents and children should be merged together (and uniqued by type?), @var above properties should be the same as @return etc.

I'd love if you could give it a try. The most recent modifications around this were when I introduced parameter name remapping based on position:

class Foo {
	/**
	 * @param A $a
         * @param B $b
         * @param C $c
	 */
	public function a($a, $b, $c) {}

}

class Bar extends Foo {

	public function a($x, $y, $z) {} // $x is A, $y is B, $z is C

}

Here are some commits:

• phpstan/phpstan-src@ae238a1
• phpstan/phpstan-src@ca37ebd

Currently the inheritDoc resolution implementation is string-based which isn't good for our purposes. PhpDocBlock is the class where it's done. resolvePhpDocBlockForProperty and resolvePhpDocBlockForMethod is what's interesting to us. The first method is called only from a single place where the property is created, resolvePhpDocBlockForMethod is called from two places - one place is for creating reflections of called methods, the other is for creating reflection of currently analysed method. It's like this because of trait analysis.

ResolvedPhpDocBlock is an object representation of a final docblock and it has the PHPDoc AST. I'm thinking we should mostly get rid of PhpDocBlock and have something like ResolvedPhpDocBlock::mergeWithParent or ResolvedPhpDocBlock::mergeWithChild (whatever direction we choose). Some ResolvedPhpDocBlock instances would exist temporarily as an intermediate representation (without inherited tags) that would get merged into the final form.

[iluuu1994]

Cool. I'll work on this soon 🙂

[ondrejmirtes]

Looking forward to it :) Try to add tests in a similar fashion as I did with the parameter name remapping :) Thank you.

[alexeyinkin]

Hi! Is anybody working on this now? Because I need this for my project.
I might take a look into it but it would take me much longer than for an experienced member. Don't want to waste time if it is in progress already.

[iluuu1994]

Jup, I'm pretty far along. Hopefully I can finish it in the next few days.

[ondrejmirtes]

@iluuu1994 Awesome! Feel free to send me your work in progress so we get a chance to turn the direction if I spot some opportunities to do something in a simpler way for example 😊

[alexeyinkin]

Any luck? Need some help?

[iluuu1994]

Very sorry, I have gotten distracted by some other things, feel free to take over. 🙂

[alexeyinkin]

I am totally new to this. Is there anything useful to be continued? Which repository and branch? Any advice? Manuals?

[iluuu1994]

The development is done in phpstan-src. master is fine. @ondrejmirtes's comment explains the challenges pretty well. The resolving of the parent docBlocks are done here.

Right now, we're only looking for the first docBlock in any parent (class or interface). But what we really want is a docBlock that is obtained by merging together all of these. It's best if you look for usages of PhpDocBlock (there aren't many) and try to replace those by merging the docBlocks instead.

The main challenge here are traits. Traits have shitty reflection. Maybe you can implement the easiest cases and then consult @ondrejmirtes for help on traits.

[ondrejmirtes]

Yeah, this feature shouldn't get blocked on traits. Inheriting doc blocks from traits maybe even isn't necessary at all.