Merge pull request #17 from leviy/only-allow-useful-type-annotations

Only allow useful @param and @return annotations

Author: nicwortel

src/LEVIY/ruleset.xml

@@ -67,6 +67,7 @@
     <rule ref="SlevomatCodingStandard.TypeHints.TypeHintDeclaration">
         <properties>
             <property name="allAnnotationsAreUseful" value="true"/>
+            <property name="enableEachParameterAndReturnInspection" value="true"/>
         </properties>
     </rule>
 
@@ -162,6 +163,7 @@
     </rule>
     <rule ref="Symfony.Commenting.FunctionComment">
         <exclude name="Symfony.Commenting.FunctionComment.MissingParamComment"/>
+        <exclude name="Symfony.Commenting.FunctionComment.ParamNameNoMatch"/>
         <exclude name="Symfony.Commenting.FunctionComment.SpacingAfterParamName"/>
     </rule>
     <rule ref="Symfony.Formatting.BlankLineBeforeReturn"/>

tests/correct/annotations.php

@@ -7,3 +7,17 @@
 function allUsefulAnnotationsAreAllowed(): void
 {
 }
+
+/**
+ * @param int[] $numbers
+ */
+function omittingUselessReturnAnnotationsIsAllowed(array $numbers): void
+{
+}
+
+/**
+ * @param int[] $numbers
+ */
+function omittingUselessParamAnnotationsIsAllowed(string $string, int $int, array $numbers, bool $bool): void
+{
+}

tests/expected.log

@@ -30,26 +30,33 @@ PHPCBF CAN FIX THE 2 MARKED SNIFF VIOLATIONS AUTOMATICALLY
 
 FILE: tests/incorrect/type-hints.php
 ------------------------------------------------------------------------------------------------------------------------
-FOUND 11 ERRORS AFFECTING 8 LINES
+FOUND 17 ERRORS AFFECTING 14 LINES
 ------------------------------------------------------------------------------------------------------------------------
   9 | ERROR | [x] Function doesNotNeedDocumentationComment() does not need documentation comment.
- 13 | ERROR | [x] There must be no whitespace between parameter type hint nullability symbol and parameter type hint of
+ 16 | ERROR | [x] Function uselessReturnAnnotation() has useless @return annotation.
+ 23 | ERROR | [x] Function uselessParamAnnotation() has useless @param annotation for parameter $string.
+ 35 | ERROR | [x] Function uselessAnnotationsWithUsefulComment() has useless @param annotation for parameter $string.
+ 37 | ERROR | [x] Function uselessAnnotationsWithUsefulComment() has useless @return annotation.
+ 46 | ERROR | [x] Function uselessAnnotationsWithUsefulAnnotation() has useless @param annotation for parameter
+    |       |     $string.
+ 48 | ERROR | [x] Function uselessAnnotationsWithUsefulAnnotation() has useless @return annotation.
+ 54 | ERROR | [x] There must be no whitespace between parameter type hint nullability symbol and parameter type hint of
     |       |     parameter $input.
- 17 | ERROR | [x] There must be exactly one space between return type hint colon and return type hint.
- 17 | ERROR | [x] There must be no whitespace between closing parenthesis and return type colon.
- 21 | ERROR | [ ] Function missingTypeHints() does not have parameter type hint nor @param annotation for its parameter
+ 58 | ERROR | [x] There must be exactly one space between return type hint colon and return type hint.
+ 58 | ERROR | [x] There must be no whitespace between closing parenthesis and return type colon.
+ 62 | ERROR | [ ] Function missingTypeHints() does not have parameter type hint nor @param annotation for its parameter
     |       |     $input.
- 21 | ERROR | [ ] Function missingTypeHints() does not have return type hint nor @return annotation for its return
+ 62 | ERROR | [ ] Function missingTypeHints() does not have return type hint nor @return annotation for its return
     |       |     value.
- 26 | ERROR | [ ] Function missingTraversableAnnotations() does not have @param annotation for its traversable
+ 67 | ERROR | [ ] Function missingTraversableAnnotations() does not have @param annotation for its traversable
     |       |     parameter $input.
- 26 | ERROR | [ ] Function missingTraversableAnnotations() does not have @return annotation for its traversable return
+ 67 | ERROR | [ ] Function missingTraversableAnnotations() does not have @return annotation for its traversable return
     |       |     value.
- 30 | ERROR | [x] Parameter $input has null default value, but is not marked as nullable.
- 35 | ERROR | [x] Expected "int" but found "integer" in @param annotation.
- 37 | ERROR | [x] Expected "bool" but found "boolean" in @return annotation.
+ 71 | ERROR | [x] Parameter $input has null default value, but is not marked as nullable.
+ 76 | ERROR | [x] Expected "int" but found "integer" in @param annotation.
+ 78 | ERROR | [x] Expected "bool" but found "boolean" in @return annotation.
 ------------------------------------------------------------------------------------------------------------------------
-PHPCBF CAN FIX THE 7 MARKED SNIFF VIOLATIONS AUTOMATICALLY
+PHPCBF CAN FIX THE 13 MARKED SNIFF VIOLATIONS AUTOMATICALLY
 ------------------------------------------------------------------------------------------------------------------------
 
 

tests/incorrect/type-hints.php

@@ -10,6 +10,47 @@ function doesNotNeedDocumentationComment(string $input): string
 {
 }
 
+/**
+ * @param int[] $numbers
+ *
+ * @return void
+ */
+function uselessReturnAnnotation(array $numbers): void
+{
+}
+
+/**
+ * @param string $string
+ * @param int[]  $numbers
+ *
+ * @return int[]
+ */
+function uselessParamAnnotation(string $string, array $numbers): array
+{
+}
+
+/**
+ * This is a useful comment that should be kept
+ *
+ * @param string $string
+ *
+ * @return void
+ */
+function uselessAnnotationsWithUsefulComment(string $string): void
+{
+}
+
+/**
+ * @whatever
+ *
+ * @param string $string
+ *
+ * @return void
+ */
+function uselessAnnotationsWithUsefulAnnotation(string $string): void
+{
+}
+
 function wrongNullabilitySymbolSpacing(? string $input): string
 {
 }
@@ -34,8 +75,8 @@ function nullableDefaultValue(string $input = null): void
 /**
  * @param integer[] $input
  *
- * @return boolean
+ * @return boolean[]
  */
-function longDocBlockTypeHints(array $input): bool
+function longDocBlockTypeHints(array $input): array
 {
 }