UselessInheritDocCommentSniff: Fixed false positives

Author: kukulich

SlevomatCodingStandard/Sniffs/Commenting/UselessInheritDocCommentSniff.php

@@ -4,7 +4,9 @@
 
 use PHP_CodeSniffer\Files\File;
 use PHP_CodeSniffer\Sniffs\Sniff;
+use SlevomatCodingStandard\Helpers\FunctionHelper;
 use SlevomatCodingStandard\Helpers\TokenHelper;
+use SlevomatCodingStandard\Helpers\TypeHintHelper;
 use const T_DOC_COMMENT_OPEN_TAG;
 use const T_DOC_COMMENT_STAR;
 use const T_DOC_COMMENT_WHITESPACE;
@@ -49,6 +51,29 @@ public function process(File $phpcsFile, $docCommentOpenPointer): void
 			return;
 		}
 
+		$docCommentOwnerPointer = TokenHelper::findNext($phpcsFile, array_merge(TokenHelper::$functionTokenCodes, TokenHelper::$typeHintTokenCodes), $tokens[$docCommentOpenPointer]['comment_closer'] + 1);
+		if (in_array($tokens[$docCommentOwnerPointer]['code'], TokenHelper::$functionTokenCodes, true)) {
+			$returnTypeHint = FunctionHelper::findReturnTypeHint($phpcsFile, $docCommentOwnerPointer);
+			if ($returnTypeHint === null) {
+				return;
+			}
+
+			if (TypeHintHelper::isSimpleIterableTypeHint($returnTypeHint->getTypeHint())) {
+				return;
+			}
+
+			$parametersTypeHints = FunctionHelper::getParametersTypeHints($phpcsFile, $docCommentOwnerPointer);
+			foreach ($parametersTypeHints as $parameterTypeHint) {
+				if ($parameterTypeHint === null) {
+					return;
+				}
+
+				if (TypeHintHelper::isSimpleIterableTypeHint($parameterTypeHint->getTypeHint())) {
+					return;
+				}
+			}
+		}
+
 		$fix = $phpcsFile->addFixableError('Useless documentation comment with @inheritDoc.', $docCommentOpenPointer, self::CODE_USELESS_INHERIT_DOC_COMMENT);
 
 		if (!$fix) {

tests/Sniffs/Commenting/UselessInheritDocCommentSniffTest.php

@@ -17,12 +17,14 @@ public function testErrors(): void
 	{
 		$report = self::checkFile(__DIR__ . '/data/uselessInheritDocCommentSniffErrors.php');
 
-		self::assertSame(4, $report->getErrorCount());
+		self::assertSame(6, $report->getErrorCount());
 
 		self::assertSniffError($report, 3, UselessInheritDocCommentSniff::CODE_USELESS_INHERIT_DOC_COMMENT);
 		self::assertSniffError($report, 11, UselessInheritDocCommentSniff::CODE_USELESS_INHERIT_DOC_COMMENT);
 		self::assertSniffError($report, 19, UselessInheritDocCommentSniff::CODE_USELESS_INHERIT_DOC_COMMENT);
 		self::assertSniffError($report, 27, UselessInheritDocCommentSniff::CODE_USELESS_INHERIT_DOC_COMMENT);
+		self::assertSniffError($report, 41, UselessInheritDocCommentSniff::CODE_USELESS_INHERIT_DOC_COMMENT);
+		self::assertSniffError($report, 49, UselessInheritDocCommentSniff::CODE_USELESS_INHERIT_DOC_COMMENT);
 
 		self::assertAllFixedInFile($report);
 	}

tests/Sniffs/Commenting/data/uselessInheritDocCommentSniffErrors.fixed.php

@@ -19,3 +19,18 @@ class ALotOfWhitespace
 {
 
 }
+
+class Errors
+{
+
+	public function parameterWithNotIterableTypeHint(bool $a): bool
+	{
+		return true;
+	}
+
+	public function withNotIterableReturnType(): bool
+	{
+		return false;
+	}
+
+}

tests/Sniffs/Commenting/data/uselessInheritDocCommentSniffErrors.php

@@ -34,3 +34,24 @@ class ALotOfWhitespace
 {
 
 }
+
+class Errors
+{
+
+	/**
+	 * {@inheritdoc}
+	 */
+	public function parameterWithNotIterableTypeHint(bool $a): bool
+	{
+		return true;
+	}
+
+	/**
+	 * {@inheritdoc}
+	 */
+	public function withNotIterableReturnType(): bool
+	{
+		return false;
+	}
+
+}

tests/Sniffs/Commenting/data/uselessInheritDocCommentSniffNoErrors.php

@@ -25,3 +25,38 @@ trait ContainsEvenSomethingElse
 {
 
 }
+
+class NoErrors
+{
+
+	/**
+	 * {@inheritdoc}
+	 */
+	public function parameterWithoutTypeHint($a): bool
+	{
+		return true;
+	}
+
+	/**
+	 * {@inheritdoc}
+	 */
+	public function iterableParameter(array $a, iterable $b): bool
+	{
+		return false;
+	}
+
+	/**
+	 * {@inheritdoc}
+	 */
+	public function withoutReturnType()
+	{
+	}
+
+	/**
+	 * {@inheritdoc}
+	 */
+	public function iterableReturnType(): array
+	{
+	}
+
+}