Make phpdoc more precise for AbstractQuery

[greg0ire]

Blocked by #9774

[derrabus]

Suggested change

	* @param ClassMetadata::FETCH_EAGER|ClassMetadata::FETCH_LAZY $fetchMode
	* @param int $fetchMode
	* @psalm-param ClassMetadata::FETCH_EAGER|ClassMetadata::FETCH_LAZY $fetchMode

I don't know how well literal types are supported outside of PHPStan and Psalm. So far, we have vendor-prefixed annotations that use them.

[derrabus]

Looking at the implementation, it seems to hide potential errors. Invalid fetch modes are healed right now, but I think, we should deprecate them, so we can throw in 3.0.

[greg0ire]

Ok, so let's keep int for now.

[derrabus]

Documenting literal types is a good idea, I think. It's just that I would vendor-prefix the @param here.

[greg0ire]

🤔 sounds like you would with with @VincentLanglet on #9778 then
In this particular instance, I think it can't hurt, and I would be eager to know what your stance is on that PR. I was wondering if we should:

• only ever document the non-deprecated path
• always document both
• decide of that on a case-by-case basis.

[greg0ire]

I think it can't hurt

It already makes the build fail though, not sure that it's a great idea.

[derrabus]

@param annotations should document the public API, the intended usage of that method. In this case: It is not intended that anyone would pass 42, 'hello world' or even an array or a cURL resource to this method although it has always been possible.

It already makes the build fail though

That's Psalm being Psalm. On 3.0, we would throw if the caller passed anything but the two allowed values, right? You would face the very same problem then. I'd argue that you cannot write that kind of input validation without Psalm complaining. PHPStan has a setting treatPhpDocTypesAsCertain for that very purpose.

[greg0ire]

Argh! a conflict!