Added DeprecatedAnnotationDeclarationSniff

Author: gmponos

README.md

@@ -1100,6 +1100,10 @@ Sniff provides the following settings:
 
 Enforces fully qualified names of classes and interfaces in phpDocs - in annotations. This results in unambiguous phpDocs.
 
+#### SlevomatCodingStandard.Commenting.DeprecatedAnnotationDeclarationSniff
+
+Reports `@deprecated` annotations without description.
+
 #### SlevomatCodingStandard.Commenting.DisallowCommentAfterCode 🔧
 
 Disallows comments after code at the same line.

SlevomatCodingStandard/Sniffs/Commenting/DeprecatedAnnotationDeclarationSniff.php

@@ -0,0 +1,50 @@
+<?php declare(strict_types = 1);
+
+namespace SlevomatCodingStandard\Sniffs\Commenting;
+
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Sniffs\Sniff;
+use SlevomatCodingStandard\Helpers\Annotation\GenericAnnotation;
+use SlevomatCodingStandard\Helpers\AnnotationHelper;
+use function count;
+use const T_DOC_COMMENT_OPEN_TAG;
+
+class DeprecatedAnnotationDeclarationSniff implements Sniff
+{
+
+	public const MISSING_DESCRIPTION = 'MissingDescription';
+
+	/** @return array<int, (int|string)> */
+	public function register(): array
+	{
+		return [T_DOC_COMMENT_OPEN_TAG];
+	}
+
+	/**
+	 * @phpcsSuppress SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
+	 * @param File $phpcsFile
+	 * @param int $docCommentStartPointer
+	 */
+	public function process(File $phpcsFile, $docCommentStartPointer): void
+	{
+		/** @var GenericAnnotation[] $annotations */
+		$annotations = AnnotationHelper::getAnnotationsByName($phpcsFile, $docCommentStartPointer, '@deprecated');
+
+		if (count($annotations) === 0) {
+			return;
+		}
+
+		foreach ($annotations as $annotation) {
+			if ($annotation->getContent() !== null) {
+				continue;
+			}
+
+			$phpcsFile->addError(
+				'Deprecated annotation must have a description.',
+				$annotation->getStartPointer(),
+				self::MISSING_DESCRIPTION
+			);
+		}
+	}
+
+}

tests/Sniffs/Commenting/DeprecatedAnnotationDeclarationSniffTest.php

@@ -0,0 +1,27 @@
+<?php declare(strict_types = 1);
+
+namespace SlevomatCodingStandard\Sniffs\Commenting;
+
+use SlevomatCodingStandard\Sniffs\TestCase;
+
+class DeprecatedAnnotationDeclarationSniffTest extends TestCase
+{
+
+	public function testNoErrors(): void
+	{
+		$report = self::checkFile(__DIR__ . '/data/deprecatedAnnotationDeclarationNoErrors.php');
+		self::assertNoSniffErrorInFile($report);
+	}
+
+	public function testErrors(): void
+	{
+		$report = self::checkFile(__DIR__ . '/data/deprecatedAnnotationDeclarationErrors.php');
+
+		self::assertSame(4, $report->getErrorCount());
+
+		foreach ([6, 12, 17, 25] as $line) {
+			self::assertSniffError($report, $line, DeprecatedAnnotationDeclarationSniff::MISSING_DESCRIPTION);
+		}
+	}
+
+}

tests/Sniffs/Commenting/data/deprecatedAnnotationDeclarationErrors.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @deprecated
+ */
+class Whatever
+{
+
+	/**
+	 * @deprecated
+	 */
+	public const DEPRECATED_WITHOUT = 'deprecated';
+
+	/**
+	 * @deprecated
+	 */
+	public function deprecatedWithoutDescriptionIsReported()
+	{
+	}
+
+	public function deprecatedVariable()
+	{
+		/** @deprecated */
+		$var = 1;
+	}
+
+}

tests/Sniffs/Commenting/data/deprecatedAnnotationDeclarationNoErrors.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+class Whatever
+{
+
+	/**
+	 * @deprecated with description
+	 */
+	public const DEPRECATED_WITH_DESCRIPTION = 'deprecated';
+
+	/**
+	 * @deprecated useSomething else
+	 */
+	public function deprecatedMethodWithDescriptionIsNotReported()
+	{
+	}
+
+	/**
+	 * Should not report the plain word deprecated inside a docblock
+	 */
+	public function deprecatedWordShouldNotBeReported()
+	{
+	}
+
+	/**
+	 * Should not report the @deprecated plain word deprecated inside a docblock
+	 */
+	public function deprecatedInDocblock()
+	{
+	}
+
+	public function deprecatedVariable()
+	{
+		/** @deprecated This var is deprecated */
+		$var = 2;
+	}
+
+	/**
+	 * @see something
+	 * @param string $var
+	 * @return void
+	 */
+	public function functionWithNoDeprecatedShouldNotBeReported(string $var): void
+	{
+	}
+
+}

tests/Sniffs/Commenting/data/deprecatedDocRequiresDescription.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @deprecated
+ */
+class Whatever
+{
+	/**
+	 * @deprecated
+	 */
+	public const DEPRECATED_WITHOUT = 'deprecated';
+
+	/**
+	 * @deprecated with description
+	 */
+	public const DEPRECATED_WITH = 'deprecated';
+
+	/**
+	 * @deprecated useSomething else
+	 */
+	public function deprecatedMethodWithDescriptionIsNotReported()
+	{
+	}
+
+	/**
+	 * @deprecated
+	 */
+	public function deprecatedWithoutDescriptionIsReported()
+	{
+	}
+
+	/**
+	 * Should not report the plain word deprecated inside a docblock
+	 */
+	public function deprecatedWordShouldNotBeReported()
+	{
+	}
+
+	/**
+	 * Should not report the @deprecated plain word deprecated inside a docblock
+	 */
+	public function deprecatedInDocblock()
+	{
+	}
+
+	public function deprecatedVariable()
+	{
+		/** @deprecated */
+		$var1 = 1;
+
+		/** @deprecated This var is deprecated */
+		$var2 = 2;
+	}
+
+	/**
+	 * @see something
+	 * @param string $var
+	 * @return void
+	 */
+	public function functionWithNoDeprecatedShouldNotBeReported(string $var): void
+	{
+	}
+}