Introduce rule RequireOneDocCommentSniff

Author: kamil-zacek

README.md

@@ -82,6 +82,7 @@ Slevomat Coding Standard for [PHP_CodeSniffer](https://github.com/PHPCSStandards
  - [SlevomatCodingStandard.Commenting.ForbiddenAnnotations](doc/commenting.md#slevomatcodingstandardcommentingforbiddenannotations-) 🔧
  - [SlevomatCodingStandard.Commenting.ForbiddenComments](doc/commenting.md#slevomatcodingstandardcommentingforbiddencomments-) 🔧
  - [SlevomatCodingStandard.Commenting.InlineDocCommentDeclaration](doc/commenting.md#slevomatcodingstandardcommentinginlinedoccommentdeclaration-) 🔧
+ - [SlevomatCodingStandard.Commenting.RequireOneDocComment](doc/commenting.md#slevomatcodingstandardcommentingrequireonedoccomment-) 🔧
  - [SlevomatCodingStandard.Commenting.RequireOneLineDocComment](doc/commenting.md#slevomatcodingstandardcommentingrequireonelinedoccomment-) 🔧
  - [SlevomatCodingStandard.Commenting.RequireOneLinePropertyDocComment](doc/commenting.md#slevomatcodingstandardcommentingrequireonelinepropertydoccomment-) 🔧
  - [SlevomatCodingStandard.Commenting.UselessFunctionDocComment](doc/commenting.md#slevomatcodingstandardcommentinguselessfunctiondoccomment-) 🔧

SlevomatCodingStandard/Sniffs/Commenting/RequireOneDocCommentSniff.php

@@ -0,0 +1,94 @@
+<?php declare(strict_types = 1);
+
+namespace SlevomatCodingStandard\Sniffs\Commenting;
+
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Sniffs\Sniff;
+use function implode;
+use function preg_match;
+use function preg_replace;
+use function preg_split;
+use function strpos;
+use function trim;
+use const T_COMMENT;
+use const T_DOC_COMMENT_OPEN_TAG;
+use const T_WHITESPACE;
+
+class RequireOneDocCommentSniff implements Sniff
+{
+
+	public const CODE_MULTIPLE_DOC_COMMENTS = 'MultipleDocComments';
+
+	/**
+	 * @return array<int, (int|string)>
+	 */
+	public function register(): array
+	{
+		return [T_DOC_COMMENT_OPEN_TAG];
+	}
+
+	public function process(File $phpcsFile, int $stackPointer): void
+	{
+		$tokens = $phpcsFile->getTokens();
+
+		$firstOpener = $stackPointer;
+		$firstCloser = $tokens[$firstOpener]['comment_closer'];
+
+		/** @var int $next */
+		$next = $phpcsFile->findNext([T_WHITESPACE], $firstCloser + 1, null, true);
+
+		if ($tokens[$next]['code'] === T_COMMENT) {
+			return;
+		}
+
+		if ($tokens[$next]['code'] !== T_DOC_COMMENT_OPEN_TAG) {
+			return;
+		}
+
+		$secondOpener = $next;
+		$secondCloser = $tokens[$secondOpener]['comment_closer'];
+
+		if ($this->isSingleLineVarDoc($phpcsFile, $firstOpener, $firstCloser)
+			&& $this->isSingleLineVarDoc($phpcsFile, $secondOpener, $secondCloser)) {
+			return;
+		}
+
+		$error = 'Only one PHPDoc comment is allowed for a documentable entity; found two adjacent doc comments.';
+		$phpcsFile->addError($error, $firstOpener, self::CODE_MULTIPLE_DOC_COMMENTS);
+	}
+
+	private function isSingleLineVarDoc(File $phpcsFile, int $opener, int $closer): bool
+	{
+		$length = $closer - $opener + 1;
+		$text = $phpcsFile->getTokensAsString($opener, $length);
+
+		if ((strpos($text, "\n") !== false) || (strpos($text, "\r") !== false)) {
+			return false;
+		}
+
+		$inner = $this->getDocInner($text);
+
+		return preg_match('/^@var\b/i', $inner) === 1 && preg_match('/\$\w+\s*$/', $inner) === 1;
+	}
+
+	private function getDocInner(string $doc): string
+	{
+		$doc = preg_replace('#\A\s*/\*\*\s*#s', '', $doc);
+		$doc = preg_replace('#\s*\*/\s*\z#s', '', $doc);
+
+		/** @var list<string> $lines */
+		$lines = preg_split("/\r\n|\n|\r/", $doc);
+
+		$clean = [];
+
+		foreach ($lines as $line) {
+			$line = preg_replace('#^\s*\*\s?#', '', $line);
+			$clean[] = $line;
+		}
+
+		$inner = implode("\n", $clean);
+
+		return trim($inner, "\n\r ");
+	}
+
+}

doc/commenting.md

@@ -90,6 +90,10 @@ Sniff provides the following settings:
 * `allowDocCommentAboveReturn`: Allows documentation comments without variable name above `return` statement.
 * `allowAboveNonAssignment`: Allows documentation comments above non-assignment if the line contains the right variable name.
 
+#### SlevomatCodingStandard.Commenting.RequireOneDocComment 
+
+Ensures that there is only one PHPDoc comment block for each entity (class, method, property, constant, etc.). This sniff prevents multiple documentation comments from being associated with a single code element, which can lead to confusion and inconsistency.
+
 #### SlevomatCodingStandard.Commenting.RequireOneLinePropertyDocComment 🔧
 
 Requires property comments with single-line content to be written as one-liners.

tests/Sniffs/Commenting/RequireOneDocCommentSniffTest.php

@@ -0,0 +1,30 @@
+<?php declare(strict_types = 1);
+
+namespace SlevomatCodingStandard\Sniffs\Commenting;
+
+use SlevomatCodingStandard\Sniffs\TestCase;
+
+class RequireOneDocCommentSniffTest extends TestCase
+{
+
+	public function testInvalidInlineDocCommentDeclarations(): void
+	{
+		$report = self::checkFile(__DIR__ . '/data/requireOneDocCommentSniff.php');
+
+		self::assertSame(4, $report->getErrorCount());
+
+		self::assertSniffError($report, 6, RequireOneDocCommentSniff::CODE_MULTIPLE_DOC_COMMENTS);
+		self::assertSniffError($report, 15, RequireOneDocCommentSniff::CODE_MULTIPLE_DOC_COMMENTS);
+		self::assertSniffError($report, 24, RequireOneDocCommentSniff::CODE_MULTIPLE_DOC_COMMENTS);
+		self::assertSniffError($report, 49, RequireOneDocCommentSniff::CODE_MULTIPLE_DOC_COMMENTS);
+	}
+
+	public function testNoErrorsWithDocCommentAboveReturnAllowed(): void
+	{
+		$report = self::checkFile(__DIR__ . '/data/oneLinePropertyDocCommentErrors.fixed.php', [
+			'allowDocCommentAboveReturn' => true,
+		]);
+		self::assertNoSniffErrorInFile($report);
+	}
+
+}

tests/Sniffs/Commenting/data/requireOneDocCommentSniff.php

@@ -0,0 +1,64 @@
+<?php
+
+use Slevomat\Foo;
+use Slevomat\FooTask;
+
+/**
+ * Description
+ */
+/**
+ * Description 2
+ */
+class Whatever
+{
+
+	/**
+	 * Description
+	 * @var string
+	 */
+	/**
+	 * @var int
+	 */
+	private $property;
+
+	/** @phpstan-assert-if-true !null $this->getApprovedTime() */
+	/** @phpstan-assert-if-true null $this->getRejectedTime() */
+	public function method()
+	{
+		/** @var int $productId */
+		/** @var Foo $issue */
+		return [1, 2, 3];
+	}
+
+	/**
+	 * @param int $a
+	 * @return void
+	 */
+	public function bar(int $a)
+	{
+		/** @var int */
+		return 5;
+	}
+
+	/**
+	 * @param int $a
+	 * @return void
+	 */
+	public function bar2(int $a)
+	{
+		/** @var int */
+		/** @var int */
+		return 5;
+	}
+
+	/**
+	 * @param FooTask $backgroundExportTask
+	 * @return bool
+	 */
+	// public function isAllowed(FooTask $task): bool;
+
+	/**
+	 * @param FooTask $backgroundExportTask
+	 */
+	// public function execute(FooTask $task): BackgroundExportFile;
+}