SlevomatCodingStandard.Commenting.UselessFunctionDocCommentSniff: It should report simple "array" as useless

kukulich · kukulich · commit 6ea0278a67db · 2024-03-09T11:47:34.000+01:00
diff --git a/SlevomatCodingStandard/Helpers/AnnotationHelper.php b/SlevomatCodingStandard/Helpers/AnnotationHelper.php
@@ -216,15 +216,21 @@ public static function isAnnotationUseless(
 			return true;
 		}
 
-		if (TypeHintHelper::isTraversableType(
-			TypeHintHelper::getFullyQualifiedTypeHint($phpcsFile, $functionPointer, $typeHint->getTypeHintWithoutNullabilitySymbol()),
-			$traversableTypeHints
-		)) {
+		$annotationType = $annotationValue->type;
+
+		if (
+			TypeHintHelper::isTraversableType(
+				TypeHintHelper::getFullyQualifiedTypeHint($phpcsFile, $functionPointer, $typeHint->getTypeHintWithoutNullabilitySymbol()),
+				$traversableTypeHints
+			)
+			&& !(
+				$annotationType instanceof IdentifierTypeNode
+				&& TypeHintHelper::isSimpleIterableTypeHint(strtolower($annotationType->name))
+			)
+		) {
 			return false;
 		}
 
-		$annotationType = $annotationValue->type;
-
 		if (AnnotationTypeHelper::containsStaticOrThisType($annotationType)) {
 			return false;
 		}
diff --git a/tests/Sniffs/Commenting/UselessFunctionDocCommentSniffTest.php b/tests/Sniffs/Commenting/UselessFunctionDocCommentSniffTest.php
@@ -19,7 +19,7 @@ public function testErrors(): void
 	{
 		$report = self::checkFile(__DIR__ . '/data/uselessFunctionDocCommentSniffErrors.php');
 
-		self::assertSame(7, $report->getErrorCount());
+		self::assertSame(8, $report->getErrorCount());
 
 		self::assertSniffError($report, 10, UselessFunctionDocCommentSniff::CODE_USELESS_DOC_COMMENT);
 		self::assertSniffError($report, 18, UselessFunctionDocCommentSniff::CODE_USELESS_DOC_COMMENT);
@@ -28,6 +28,7 @@ public function testErrors(): void
 		self::assertSniffError($report, 39, UselessFunctionDocCommentSniff::CODE_USELESS_DOC_COMMENT);
 		self::assertSniffError($report, 47, UselessFunctionDocCommentSniff::CODE_USELESS_DOC_COMMENT);
 		self::assertSniffError($report, 54, UselessFunctionDocCommentSniff::CODE_USELESS_DOC_COMMENT);
+		self::assertSniffError($report, 61, UselessFunctionDocCommentSniff::CODE_USELESS_DOC_COMMENT);
 
 		self::assertAllFixedInFile($report);
 	}
diff --git a/tests/Sniffs/Commenting/data/uselessFunctionDocCommentSniffErrors.fixed.php b/tests/Sniffs/Commenting/data/uselessFunctionDocCommentSniffErrors.fixed.php
@@ -33,4 +33,8 @@ public function onlyParameterWithoutTypeArray(array $a): void
 	{
 	}
 
+	public function onlyParameterWithSimpleArrayType(array $a): void
+	{
+	}
+
 }
diff --git a/tests/Sniffs/Commenting/data/uselessFunctionDocCommentSniffErrors.php b/tests/Sniffs/Commenting/data/uselessFunctionDocCommentSniffErrors.php
@@ -55,4 +55,11 @@ public function onlyParameterWithoutTypeArray(array $a): void
 	{
 	}
 
+	/**
+	 * @param array $a
+	 */
+	public function onlyParameterWithSimpleArrayType(array $a): void
+	{
+	}
+
 }
diff --git a/tests/Sniffs/TypeHints/ParameterTypeHintSniffTest.php b/tests/Sniffs/TypeHints/ParameterTypeHintSniffTest.php
@@ -30,7 +30,7 @@ public function testErrors(): void
 			'traversableTypeHints' => ['Traversable', '\ArrayIterator'],
 		]);
 
-		self::assertSame(51, $report->getErrorCount());
+		self::assertSame(52, $report->getErrorCount());
 
 		self::assertSniffError($report, 6, ParameterTypeHintSniff::CODE_MISSING_ANY_TYPE_HINT);
 		self::assertSniffError($report, 14, ParameterTypeHintSniff::CODE_MISSING_NATIVE_TYPE_HINT);
@@ -43,6 +43,7 @@ public function testErrors(): void
 		self::assertSniffError($report, 67, ParameterTypeHintSniff::CODE_USELESS_ANNOTATION);
 		self::assertSniffError($report, 74, ParameterTypeHintSniff::CODE_MISSING_TRAVERSABLE_TYPE_HINT_SPECIFICATION);
 		self::assertSniffError($report, 80, ParameterTypeHintSniff::CODE_MISSING_TRAVERSABLE_TYPE_HINT_SPECIFICATION);
+		self::assertSniffError($report, 80, ParameterTypeHintSniff::CODE_USELESS_ANNOTATION);
 		self::assertSniffError($report, 90, ParameterTypeHintSniff::CODE_MISSING_NATIVE_TYPE_HINT);
 		self::assertSniffError($report, 96, ParameterTypeHintSniff::CODE_MISSING_TRAVERSABLE_TYPE_HINT_SPECIFICATION);
 		self::assertSniffError($report, 98, ParameterTypeHintSniff::CODE_MISSING_NATIVE_TYPE_HINT);
diff --git a/tests/Sniffs/TypeHints/PropertyTypeHintSniffTest.php b/tests/Sniffs/TypeHints/PropertyTypeHintSniffTest.php
@@ -57,7 +57,7 @@ public function testEnabledNativeErrors(): void
 			'traversableTypeHints' => ['Traversable'],
 		]);
 
-		self::assertSame(49, $report->getErrorCount());
+		self::assertSame(50, $report->getErrorCount());
 
 		self::assertSniffError($report, 6, PropertyTypeHintSniff::CODE_MISSING_ANY_TYPE_HINT);
 		self::assertSniffError($report, 11, PropertyTypeHintSniff::CODE_MISSING_NATIVE_TYPE_HINT);
@@ -68,6 +68,7 @@ public function testEnabledNativeErrors(): void
 		self::assertSniffError($report, 34, PropertyTypeHintSniff::CODE_USELESS_ANNOTATION);
 		self::assertSniffError($report, 38, PropertyTypeHintSniff::CODE_MISSING_TRAVERSABLE_TYPE_HINT_SPECIFICATION);
 		self::assertSniffError($report, 41, PropertyTypeHintSniff::CODE_MISSING_TRAVERSABLE_TYPE_HINT_SPECIFICATION);
+		self::assertSniffError($report, 41, PropertyTypeHintSniff::CODE_USELESS_ANNOTATION);
 		self::assertSniffError($report, 48, PropertyTypeHintSniff::CODE_MISSING_NATIVE_TYPE_HINT);
 		self::assertSniffError($report, 51, PropertyTypeHintSniff::CODE_MISSING_TRAVERSABLE_TYPE_HINT_SPECIFICATION);
 		self::assertSniffError($report, 53, PropertyTypeHintSniff::CODE_MISSING_NATIVE_TYPE_HINT);
diff --git a/tests/Sniffs/TypeHints/ReturnTypeHintSniffTest.php b/tests/Sniffs/TypeHints/ReturnTypeHintSniffTest.php
@@ -33,7 +33,7 @@ public function testErrors(): void
 			'traversableTypeHints' => ['Traversable', '\ArrayIterator'],
 		]);
 
-		self::assertSame(61, $report->getErrorCount());
+		self::assertSame(62, $report->getErrorCount());
 
 		self::assertSniffError($report, 6, ReturnTypeHintSniff::CODE_MISSING_ANY_TYPE_HINT);
 		self::assertSniffError($report, 14, ReturnTypeHintSniff::CODE_MISSING_NATIVE_TYPE_HINT);
@@ -45,6 +45,7 @@ public function testErrors(): void
 		self::assertSniffError($report, 60, ReturnTypeHintSniff::CODE_USELESS_ANNOTATION);
 		self::assertSniffError($report, 67, ReturnTypeHintSniff::CODE_MISSING_TRAVERSABLE_TYPE_HINT_SPECIFICATION);
 		self::assertSniffError($report, 73, ReturnTypeHintSniff::CODE_MISSING_TRAVERSABLE_TYPE_HINT_SPECIFICATION);
+		self::assertSniffError($report, 73, ReturnTypeHintSniff::CODE_USELESS_ANNOTATION);
 		self::assertSniffError($report, 80, ReturnTypeHintSniff::CODE_MISSING_NATIVE_TYPE_HINT);
 		self::assertSniffError($report, 88, ReturnTypeHintSniff::CODE_MISSING_NATIVE_TYPE_HINT);
 		self::assertSniffError($report, 92, ReturnTypeHintSniff::CODE_MISSING_NATIVE_TYPE_HINT);
diff --git a/tests/Sniffs/TypeHints/data/parameterTypeHintErrors.fixed.php b/tests/Sniffs/TypeHints/data/parameterTypeHintErrors.fixed.php
@@ -73,7 +73,6 @@ public function missingAnnotationForTraversable(array $a)
 	}
 
 	/**
-	 * @param array $a
 	 */
 	public function missingItemsSpecification(array $a)
 	{
diff --git a/tests/Sniffs/TypeHints/data/parameterTypeHintNoErrors.php b/tests/Sniffs/TypeHints/data/parameterTypeHintNoErrors.php
@@ -48,6 +48,7 @@ private function isSniffCodeMissingNativeTypeHintSuppressed($a)
 
 	/**
 	 * @phpcsSuppress SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingTraversableTypeHintSpecification
+	 * @phpcsSuppress SlevomatCodingStandard.TypeHints.ParameterTypeHint.UselessAnnotation
 	 * @param array $a
 	 */
 	private function isSniffCodeMissingTravesableTypeHintSpecificationSuppressed(array $a)
diff --git a/tests/Sniffs/TypeHints/data/propertyTypeHintEnabledNativeErrors.fixed.php b/tests/Sniffs/TypeHints/data/propertyTypeHintEnabledNativeErrors.fixed.php
@@ -31,9 +31,6 @@ class Whatever
 
 	public array $missingAnnotationForTraversable;
 
-	/**
-	 * @var array
-	 */
 	public array $missingItemsSpecification;
 
 	/**
diff --git a/tests/Sniffs/TypeHints/data/propertyTypeHintEnabledNativeNoErrors.php b/tests/Sniffs/TypeHints/data/propertyTypeHintEnabledNativeNoErrors.php
@@ -26,6 +26,7 @@ class Whatever
 
 	/**
 	 * @phpcsSuppress SlevomatCodingStandard.TypeHints.PropertyTypeHint.MissingTraversableTypeHintSpecification
+	 * @phpcsSuppress SlevomatCodingStandard.TypeHints.PropertyTypeHint.UselessAnnotation
 	 * @var array
 	 */
 	private array $isSniffCodeMissingTravesableTypeHintSpecificationSuppressed;
diff --git a/tests/Sniffs/TypeHints/data/returnTypeHintErrors.fixed.php b/tests/Sniffs/TypeHints/data/returnTypeHintErrors.fixed.php
@@ -67,7 +67,6 @@ public function missingAnnotationForTraversable(): array
 	}
 
 	/**
-	 * @return array
 	 */
 	public function missingItemsSpecification(): array
 	{
diff --git a/tests/Sniffs/TypeHints/data/returnTypeHintNoErrors.php b/tests/Sniffs/TypeHints/data/returnTypeHintNoErrors.php
@@ -55,6 +55,7 @@ abstract public function isSniffCodeMissingNativeTypeHintSuppressedWithVoid();
 
 	/**
 	 * @phpcsSuppress SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingTraversableTypeHintSpecification
+	 * @phpcsSuppress SlevomatCodingStandard.TypeHints.ReturnTypeHint.UselessAnnotation
 	 * @return array
 	 */
 	private function isSniffCodeMissingTravesableTypeHintSpecificationSuppressed(): array

Original file line number	Diff line number	Diff line change
`@@ -19,7 +19,7 @@ public function testErrors(): void`
`19`	`19`	`{`
`20`	`20`	`$report = self::checkFile(__DIR__ . '/data/uselessFunctionDocCommentSniffErrors.php');`
`21`	`21`
`22`		`- self::assertSame(7, $report->getErrorCount());`
	`22`	`+ self::assertSame(8, $report->getErrorCount());`
`23`	`23`
`24`	`24`	`self::assertSniffError($report, 10, UselessFunctionDocCommentSniff::CODE_USELESS_DOC_COMMENT);`
`25`	`25`	`self::assertSniffError($report, 18, UselessFunctionDocCommentSniff::CODE_USELESS_DOC_COMMENT);`
`@@ -28,6 +28,7 @@ public function testErrors(): void`
`28`	`28`	`self::assertSniffError($report, 39, UselessFunctionDocCommentSniff::CODE_USELESS_DOC_COMMENT);`
`29`	`29`	`self::assertSniffError($report, 47, UselessFunctionDocCommentSniff::CODE_USELESS_DOC_COMMENT);`
`30`	`30`	`self::assertSniffError($report, 54, UselessFunctionDocCommentSniff::CODE_USELESS_DOC_COMMENT);`
	`31`	`+ self::assertSniffError($report, 61, UselessFunctionDocCommentSniff::CODE_USELESS_DOC_COMMENT);`
`31`	`32`
`32`	`33`	`self::assertAllFixedInFile($report);`
`33`	`34`	`}`
Original file line number	Diff line number	Diff line change
`@@ -33,4 +33,8 @@ public function onlyParameterWithoutTypeArray(array $a): void`
`33`	`33`	`{`
`34`	`34`	`}`
`35`	`35`
	`36`	`+ public function onlyParameterWithSimpleArrayType(array $a): void`
	`37`	`+ {`
	`38`	`+ }`
	`39`	`+`
`36`	`40`	`}`
Original file line number	Diff line number	Diff line change
`@@ -55,4 +55,11 @@ public function onlyParameterWithoutTypeArray(array $a): void`
`55`	`55`	`{`
`56`	`56`	`}`
`57`	`57`
	`58`	`+ /**`
	`59`	`+ * @param array $a`
	`60`	`+ */`
	`61`	`+ public function onlyParameterWithSimpleArrayType(array $a): void`
	`62`	`+ {`
	`63`	`+ }`
	`64`	`+`
`58`	`65`	`}`
Original file line number	Diff line number	Diff line change
`@@ -73,7 +73,6 @@ public function missingAnnotationForTraversable(array $a)`
`73`	`73`	`}`
`74`	`74`
`75`	`75`	`/**`
`76`		`- * @param array $a`
`77`	`76`	`*/`
`78`	`77`	`public function missingItemsSpecification(array $a)`
`79`	`78`	`{`