CS: enable no_superfluous_phpdoc_tags rule and updated deprecated o…

…nes (zircote#1558)

.php-cs-fixer.dist.php

@@ -1,23 +1,22 @@
 <?php declare(strict_types=1);
 
-use OpenApi\Tools\CSFixer\ScopedLicenseFixer;
 use OpenApi\Tools\CSFixer\ScopedDeclareStrictTypesFixer;
+use OpenApi\Tools\CSFixer\ScopedLicenseFixer;
 
 $finder = PhpCsFixer\Finder::create()
     ->path('src')->name('*.php')
     ->path('tests')->name('*.php')
-        // ContextTest::testFullyQualifiedName relies on the 'use Exception' statement...
-        ->filter(function (\SplFileInfo $file) {
-            return !strpos($file->getPathname(), 'tests/Fixtures/Customer.php');
-        })
+    // ContextTest::testFullyQualifiedName relies on the 'use Exception' statement...
+    ->filter(function (\SplFileInfo $file) {
+        return !strpos($file->getPathname(), 'tests/Fixtures/Customer.php');
+    })
     ->path('Examples')->name('*.php')
-        ->filter(function (\SplFileInfo $file) {
-            return !strpos($file->getPathname(), 'Examples/petstore-3.0/Petstore.php')
-                && !strpos($file->getPathname(), 'Examples/misc/OpenApiSpec.php');
-        })
+    ->filter(function (\SplFileInfo $file) {
+        return !strpos($file->getPathname(), 'Examples/petstore-3.0/Petstore.php')
+            && !strpos($file->getPathname(), 'Examples/misc/OpenApiSpec.php');
+    })
     ->path('tools')->name('*.php')
-    ->in(__DIR__)
-;
+    ->in(__DIR__);
 
 return (new PhpCsFixer\Config())
     ->registerCustomFixers([
@@ -35,11 +34,11 @@
         'visibility_required' => true,
         'cast_spaces' => ['space' => 'single'],
         'concat_space' => ['spacing' => 'one'],
-        'function_typehint_space' => true,
+        'type_declaration_spaces' => true,
         'lowercase_cast' => true,
         'magic_constant_casing' => true,
         'class_attributes_separation' => ['elements' => ['method' => 'one']],
-        'single_blank_line_before_namespace' => true,
+        'blank_lines_before_namespace' => true,
         'no_singleline_whitespace_before_semicolons' => true,
         'no_spaces_around_offset' => true,
         'no_whitespace_before_comma_in_array' => true,
@@ -49,24 +48,23 @@
         'no_blank_lines_after_phpdoc' => true,
         'no_extra_blank_lines' => true,
         'return_type_declaration' => ['space_before' => 'none'],
-        'no_trailing_comma_in_list_call' => true,
-        'no_trailing_comma_in_singleline_array' => true,
+        'no_trailing_comma_in_singleline' => true,
         'no_unneeded_control_parentheses' => true,
-        'no_unneeded_curly_braces' => true,
+        'no_unneeded_braces' => true,
         'short_scalar_cast' => true,
         'space_after_semicolon' => true,
         'ternary_operator_spaces' => true,
         'trailing_comma_in_multiline' => true,
         'trim_array_spaces' => true,
-        'single_space_after_construct' => true,
+        'single_space_around_construct' => true,
         'single_line_comment_spacing' => true,
         'fully_qualified_strict_types' => true,
         'global_namespace_import' => ['import_classes' => false, 'import_constants' => null, 'import_functions' => null],
 
         'nullable_type_declaration_for_default_null_value' => true,
 
         'no_empty_phpdoc' => true,
-        // 7.3 only 'no_superfluous_phpdoc_tags' => true,
+        'no_superfluous_phpdoc_tags' => true,
         'phpdoc_align' => true,
         'general_phpdoc_tag_rename' => true,
         'phpdoc_inline_tag_normalizer' => true,
@@ -85,5 +83,4 @@
         'phpdoc_no_empty_return' => true,
         'phpdoc_no_alias_tag' => true,
     ])
-    ->setFinder($finder)
-;
+    ->setFinder($finder);

src/Analysers/DocBlockParser.php

@@ -53,8 +53,7 @@ public function setAliases(array $aliases): void
     /**
      * Use doctrine to parse the comment block and return the detected annotations.
      *
-     * @param string  $comment a T_DOC_COMMENT
-     * @param Context $context
+     * @param string $comment a T_DOC_COMMENT
      *
      * @return array<OA\AbstractAnnotation>
      */

src/Annotations/AbstractAnnotation.php

@@ -156,9 +156,6 @@ public function __get(string $property)
         $this->_context->logger->warning('Property "' . $property . '" doesn\'t exist in a ' . $this->identity() . ', existing properties: "' . implode('", "', array_keys($properties)) . '" in ' . $this->_context);
     }
 
-    /**
-     * @param mixed $value
-     */
     public function __set(string $property, $value): void
     {
         $fields = get_object_vars($this);
@@ -287,9 +284,6 @@ public function __debugInfo()
         return $properties;
     }
 
-    /**
-     * @return mixed
-     */
     #[\ReturnTypeWillChange]
     public function jsonSerialize()
     {
@@ -741,8 +735,6 @@ private function validateDefaultTypes(string $type, $value): bool
 
     /**
      * Validate array type.
-     *
-     * @param mixed $value
      */
     private function validateArrayType($value): bool
     {
@@ -764,7 +756,6 @@ private function validateArrayType($value): bool
     /**
      * Wrap the context with a reference to the annotation it is nested in.
      *
-     * @param AbstractAnnotation $annotation
      *
      * @return AbstractAnnotation
      */

src/Annotations/Link.php

@@ -75,8 +75,6 @@ class Link extends AbstractAnnotation
 
     /**
      * A literal value or {expression} to use as a request body when calling the target operation.
-     *
-     * @var mixed
      */
     public $requestBody = Generator::UNDEFINED;
 

src/Annotations/MediaType.php

@@ -39,8 +39,6 @@ class MediaType extends AbstractAnnotation
      *
      * Furthermore, if referencing a schema which contains an example,
      * the example value shall override the example provided by the schema.
-     *
-     * @var mixed
      */
     public $example = Generator::UNDEFINED;
 

src/Annotations/Parameter.php

@@ -143,8 +143,6 @@ class Parameter extends AbstractAnnotation
      * The example object is mutually exclusive of the examples object.
      * Furthermore, if referencing a schema which contains an example, the example value shall override the example provided by the schema.
      * To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.
-     *
-     * @var mixed
      */
     public $example = Generator::UNDEFINED;
 

src/Annotations/Schema.php

@@ -133,8 +133,6 @@ class Schema extends AbstractAnnotation
      * Sets a default value to the parameter. The type of the value depends on the defined type.
      *
      * @see [JSON schema validation](http://json-schema.org/latest/json-schema-validation.html#anchor101)
-     *
-     * @var mixed
      */
     public $default = Generator::UNDEFINED;
 
@@ -318,8 +316,6 @@ class Schema extends AbstractAnnotation
      *
      * To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
      * contain the example with escaping where necessary.
-     *
-     * @var mixed
      */
     public $example = Generator::UNDEFINED;
 
@@ -407,8 +403,6 @@ class Schema extends AbstractAnnotation
 
     /**
      * http://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.1.3.
-     *
-     * @var mixed
      */
     public $const = Generator::UNDEFINED;
 

src/Attributes/OperationTrait.php

@@ -11,7 +11,6 @@
 trait OperationTrait
 {
     /**
-     * @param array                    $security
      * @param Server[]                 $servers
      * @param string[]                 $tags
      * @param Parameter[]              $parameters

src/Attributes/Schema.php

@@ -22,7 +22,6 @@ class Schema extends \OpenApi\Annotations\Schema
      * @param array<Schema|\OpenApi\Annotations\Schema>                     $allOf
      * @param array<Schema|\OpenApi\Annotations\Schema>                     $anyOf
      * @param array<Schema|\OpenApi\Annotations\Schema>                     $oneOf
-     * @param mixed                                                         $const
      * @param array<string,mixed>|null                                      $x
      * @param Attachable[]|null                                             $attachables
      */

src/Generator.php

@@ -124,9 +124,6 @@ public function pop(): void
         };
     }
 
-    /**
-     * @param mixed $value
-     */
     public static function isDefault($value): bool
     {
         return $value === Generator::UNDEFINED;

src/Processors/AugmentParameters.php

@@ -29,8 +29,6 @@ public function isAugmentOperationParameters(): bool
 
     /**
      * If set to <code>true</code> try to find operation parameter descriptions in the operation docblock.
-     *
-     * @param bool $augmentOperationParameters
      */
     public function setAugmentOperationParameters(bool $augmentOperationParameters): void
     {

src/Processors/OperationId.php

@@ -29,8 +29,6 @@ public function isHash(): bool
 
     /**
      *  If set to <code>true</code> generate ids (md5) instead of clear text operation ids.
-     *
-     * @param bool $hash
      */
     public function setHash(bool $hash): OperationId
     {

src/Serializer.php

@@ -128,10 +128,6 @@ protected function doDeserialize(\stdClass $c, string $class, Context $context):
 
     /**
      * Deserialize the annotation's property.
-     *
-     * @param mixed $value
-     *
-     * @return mixed
      */
     protected function doDeserializeProperty(OA\AbstractAnnotation $annotation, string $property, $value, Context $context)
     {

tests/Annotations/AttributesSyncTest.php

@@ -116,7 +116,7 @@ protected function prepDocComment(string $docComment): array
 
     protected function propertyType(\ReflectionProperty $property): ?string
     {
-        $var = null;
+        $var = 'mixed';
         foreach ($this->prepDocComment($property->getDocComment()) as $line) {
             if (substr($line, 0, 5) === '@var ') {
                 $var = trim(substr($line, 5));

tests/Fixtures/Annotations/CustomAttachable.php

@@ -16,8 +16,6 @@ class CustomAttachable extends OA\Attachable
 {
     /**
      * The attribute value.
-     *
-     * @var mixed
      */
     public $value = Generator::UNDEFINED;
 

tests/Fixtures/Attributes/CustomAttachable.php

@@ -14,8 +14,6 @@ class CustomAttachable extends OAT\Attachable
 {
     /**
      * The attribute value.
-     *
-     * @var mixed
      */
     public $value = Generator::UNDEFINED;
 

tests/Fixtures/Scratch/ComplexCustomAttributes.php

@@ -23,10 +23,6 @@ class Schema extends OAT\Schema
 {
     /**
      * @param class-string $of
-     * @param string|null  $description
-     * @param array        $optional
-     * @param int|null     $minLength
-     * @param int|null     $maxLength
      *
      * @throws \ReflectionException
      */

tests/Fixtures/Scratch/MergeTraits.php

@@ -15,8 +15,6 @@ trait HasId
      *     format="int64",
      *     readOnly=true,
      * )
-     *
-     * @var int
      */
     public int $id;
 }

tests/Fixtures/Scratch/PromotedProperty.php

@@ -14,8 +14,6 @@ class PromotedPropertyDescription
 {
     /**
      * Property name.
-     *
-     * @var string
      */
     #[OAT\Property(property: 'thename')]
     public string $name = '';

tests/Fixtures/TypedProperties.php

@@ -72,8 +72,6 @@ class TypedProperties
     public string $annotationTrumpsNative;
 
     /**
-     * @var string
-     *
      * @OA\Property(
      *     type="integer",
      * )

tests/OpenApiTestCase.php

@@ -118,7 +118,6 @@ public function assertOpenApiLogEntryContains(string $needle, string $message =
      *
      * @param array|OA\OpenApi|\stdClass|string $actual     The generated output
      * @param array|OA\OpenApi|\stdClass|string $expected   The specification
-     * @param string                            $message
      * @param bool                              $normalized flag indicating whether the inputs are already normalized or
      *                                                      not
      */
@@ -255,8 +254,6 @@ protected function annotationsFromDocBlockParser(string $docBlock, array $extraA
 
     /**
      * Collect list of all non-abstract annotation classes.
-     *
-     * @return array
      */
     public function allAnnotationClasses(): array
     {
@@ -278,8 +275,6 @@ public function allAnnotationClasses(): array
 
     /**
      * Collect list of all non-abstract attribute classes.
-     *
-     * @return array
      */
     public function allAttributeClasses(): array
     {