Generate valid phpdoc param tags (#1457)

* Fix the phpdoc of the RequestContext

* Generate valid phpdoc param tags

When an array shape key starts with a `@` like `@region`, it must be
quoted in the phpdoc as the unquoted one would be interpreted as the
next phpdoc tag.

* Use an unsealed shape for the type in Input

This avoids reports about passing extra keys from child classes in
Psalm.

* Allow passing null as the region in the input

The base input class already accept null values in addition to omitted
values for the region.

* Update the psalm baseline

* Disallow invalid docblocks in Psalm as well

Author: stof

src/FirehoseClient.php

@@ -58,8 +58,7 @@ class FirehoseClient extends AbstractApi
      * @param array{
      *   DeliveryStreamName: string,
      *   Record: Record|array,
-     *
-     *   @region?: string,
+     *   '@region'?: string|null,
      * }|PutRecordInput $input
      *
      * @throws ResourceNotFoundException
@@ -136,8 +135,7 @@ public function putRecord($input): PutRecordOutput
      * @param array{
      *   DeliveryStreamName: string,
      *   Records: Record[],
-     *
-     *   @region?: string,
+     *   '@region'?: string|null,
      * }|PutRecordBatchInput $input
      *
      * @throws ResourceNotFoundException

src/Input/PutRecordBatchInput.php

@@ -32,8 +32,7 @@ final class PutRecordBatchInput extends Input
      * @param array{
      *   DeliveryStreamName?: string,
      *   Records?: Record[],
-     *
-     *   @region?: string,
+     *   '@region'?: string|null,
      * } $input
      */
     public function __construct(array $input = [])

src/Input/PutRecordInput.php

@@ -32,8 +32,7 @@ final class PutRecordInput extends Input
      * @param array{
      *   DeliveryStreamName?: string,
      *   Record?: Record|array,
-     *
-     *   @region?: string,
+     *   '@region'?: string|null,
      * } $input
      */
     public function __construct(array $input = [])