Improve some PHPdocs based on existing Symfony stubs in PHPstan and Psalm

[wouterj]

Q	A
Branch?	6.2
Bug fix?	no
New feature?	no
Deprecations?	no (strictly spoken yes, as I guess DebugClassLoader will trigger deprecations for some now?)
Tickets	Replaces #40783
License	MIT
Doc PR	https://github.com/symfony/symfony-docs/pull/17064

Todo

• [x] Review the Psalm check of this PR
• [x] Test the changes with DebugClassLoader in a real app

Description

This PR adds some more information to the PHPdoc of Symfony classes. By moving the information from the current stubs of static analyzers into Symfony itself: (1) we can improve the experience for all users, (2) reduce false-positives from our own Psalm check and (3) make sure they are in sync with changes done on these classes.

To avoid a PR that is too big to review and maintain, the scope of this PR is deliberately kept narrow:

• Only PHPdoc from either Psalm's Symfony stubs or PHPStan's Symfony stubs is added
• The PHPdoc MUST NOT break PHPstorm
• The PHPdoc MUST be supported by both PHPstan and Psalm (those are the only two static analyzers that currently ship an official Symfony plugin afaik)
• The PHPdoc SHOULD NOT duplicate anything that can already be deduced from either PHP's type declarations or already existing PHPdoc.
• The PHPdoc MUST document the contract and NOT be added to fit a 95% use-case or improve auto-completion.

EDIT: Replaced the guidelines by https://github.com/symfony/symfony-docs/pull/17064

On top of this, to get this PR approved quicker, I've left out all stubs from the Form (based on the discussions in #40783) and most of PHPStan's Envelope stub (due to complexity of the PHPdoc).

[stof]

@wouterj you need to update the .github/expected-missing-return-types.diff file to account for the change in Command::getHelper()

[wouterj]

This one is ready to merge now imho

[wouterj]

Depending on $k, this may access the array with a non scalar key. Should we modify the code and throw an exception or should we specify $k harder?

This is a good catch by Psalm that is easy to produce in a real Symfony app:

parameters:
    some_list: [1, 2, 3]
    broken_parameter:
        '%some_list%': foo

Note that resolveString() already has a nice exception message if the array key would have been 'app.%some_list%'. I've added a check and exception for this newly discovered case.

[nicolas-grekas]

Thank you @wouterj.

[nicolas-grekas]

And thank you @mdeboer also!