minor #47016 Improve some PHPdocs based on existing Symfony stubs in PHPstan and Psalm (mdeboer, wouterj)

This PR was merged into the 6.2 branch.

Discussion
----------

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

| 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        | symfony/symfony-docs#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.

<s>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](https://github.com/psalm/psalm-plugin-symfony/tree/master/src/Stubs) or [PHPStan's Symfony stubs](https://github.com/phpstan/phpstan-symfony/tree/1.2.x/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.</s>

EDIT: Replaced the guidelines by symfony/symfony-docs#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](https://github.com/psalm/psalm-plugin-symfony/blob/master/src/Stubs/common/Component/Messenger/Envelope.stubphp) (due to complexity of the PHPdoc).

Commits
-------

f5a802ab85 [DependencyInjection] Add nice exception when using non-scalar parameter as array key
fa7703ba4a [ErrorHandler] Do not patch return types that are not a valid PHP type
38ab6de900 Improve some PHPdocs based on existing Symfony stubs in PHPstan and Psalm

Author: nicolas-grekas

SerializerInterface.php

@@ -19,14 +19,20 @@ interface SerializerInterface
     /**
      * Serializes data in the appropriate format.
      *
-     * @param mixed  $data    Any data
-     * @param string $format  Format name
-     * @param array  $context Options normalizers/encoders have access to
+     * @param array<string, mixed> $context Options normalizers/encoders have access to
      */
     public function serialize(mixed $data, string $format, array $context = []): string;
 
     /**
      * Deserializes data into the given type.
+     *
+     * @template TObject of object
+     * @template TType of string|class-string<TObject>
+     *
+     * @param TType                $type
+     * @param array<string, mixed> $context
+     *
+     * @psalm-return (TType is class-string<TObject> ? TObject : mixed)
      */
     public function deserialize(mixed $data, string $type, string $format, array $context = []): mixed;
 }