From d9cab8c6ecb1cdd892b2e41134903914437ff514 Mon Sep 17 00:00:00 2001 From: Claudiu Cristea Date: Fri, 27 Sep 2024 18:21:41 +0200 Subject: [PATCH 1/6] First try --- .../Commenting/FunctionCommentSniff.php | 29 +++++++++++++++---- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php b/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php index 8db59805..c8833592 100644 --- a/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php +++ b/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php @@ -24,6 +24,11 @@ class FunctionCommentSniff implements Sniff { + /** + * @var array + */ + public $commentProhibitedFunctions = []; + /** * A map of invalid data types to valid ones for param and return documentation. * @@ -93,14 +98,29 @@ public function process(File $phpcsFile, $stackPtr) break; } + if (isset($tokens[$commentEnd]['comment_opener'])) { + $commentStart = $tokens[$commentEnd]['comment_opener']; + } - // Constructor methods are exempt from requiring a docblock. - // @see https://www.drupal.org/project/coder/issues/3400560. $methodName = $phpcsFile->getDeclarationName($stackPtr); - if ($methodName === '__construct' - && $tokens[$commentEnd]['code'] !== T_DOC_COMMENT_CLOSE_TAG + if ($tokens[$commentEnd]['code'] !== T_DOC_COMMENT_CLOSE_TAG && $tokens[$commentEnd]['code'] !== T_COMMENT ) { + if ($methodName === '__construct') { + // Constructor methods are exempt from requiring a docblock. + // @see https://www.drupal.org/project/coder/issues/3400560. + return; + } + } + elseif (in_array($methodName, $this->commentProhibitedFunctions, true)) { + // Method prohibited to have docblock. + $fix = $phpcsFile->addFixableError("It's forbidden to document $methodName function", $stackPtr, 'DocProhibited'); + if ($fix === true) { + for ($i = $commentStart; $i <= $commentEnd; $i++) { + $phpcsFile->fixer->replaceToken($i, ''); + } + } + return; } @@ -139,7 +159,6 @@ public function process(File $phpcsFile, $stackPtr) return; } - $commentStart = $tokens[$commentEnd]['comment_opener']; foreach ($tokens[$commentStart]['comment_tags'] as $tag) { // This is a file comment, not a function comment. if ($tokens[$tag]['content'] === '@file') { From e4783641b623d7847ac92541cf2c600cb3121d4c Mon Sep 17 00:00:00 2001 From: Claudiu Cristea Date: Fri, 27 Sep 2024 19:00:32 +0200 Subject: [PATCH 2/6] Coding standards --- .../Drupal/Sniffs/Commenting/FunctionCommentSniff.php | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php b/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php index c8833592..e549c3b8 100644 --- a/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php +++ b/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php @@ -25,6 +25,8 @@ class FunctionCommentSniff implements Sniff { /** + * List of methods that are prohibited to have docblock. + * * @var array */ public $commentProhibitedFunctions = []; @@ -98,7 +100,8 @@ public function process(File $phpcsFile, $stackPtr) break; } - if (isset($tokens[$commentEnd]['comment_opener'])) { + + if (isset($tokens[$commentEnd]['comment_opener']) === true) { $commentStart = $tokens[$commentEnd]['comment_opener']; } @@ -111,13 +114,12 @@ public function process(File $phpcsFile, $stackPtr) // @see https://www.drupal.org/project/coder/issues/3400560. return; } - } - elseif (in_array($methodName, $this->commentProhibitedFunctions, true)) { + } else if (in_array($methodName, $this->commentProhibitedFunctions, true) === true) { // Method prohibited to have docblock. $fix = $phpcsFile->addFixableError("It's forbidden to document $methodName function", $stackPtr, 'DocProhibited'); if ($fix === true) { for ($i = $commentStart; $i <= $commentEnd; $i++) { - $phpcsFile->fixer->replaceToken($i, ''); + $phpcsFile->fixer->replaceToken($i, ''); } } From f87d421ee6aa2971978320acad4c78aa03073aee Mon Sep 17 00:00:00 2001 From: Claudiu Cristea Date: Fri, 27 Sep 2024 19:08:53 +0200 Subject: [PATCH 3/6] PHPStan issue --- .../Drupal/Sniffs/Commenting/FunctionCommentSniff.php | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php b/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php index e549c3b8..ccd6e334 100644 --- a/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php +++ b/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php @@ -101,10 +101,6 @@ public function process(File $phpcsFile, $stackPtr) break; } - if (isset($tokens[$commentEnd]['comment_opener']) === true) { - $commentStart = $tokens[$commentEnd]['comment_opener']; - } - $methodName = $phpcsFile->getDeclarationName($stackPtr); if ($tokens[$commentEnd]['code'] !== T_DOC_COMMENT_CLOSE_TAG && $tokens[$commentEnd]['code'] !== T_COMMENT @@ -118,7 +114,7 @@ public function process(File $phpcsFile, $stackPtr) // Method prohibited to have docblock. $fix = $phpcsFile->addFixableError("It's forbidden to document $methodName function", $stackPtr, 'DocProhibited'); if ($fix === true) { - for ($i = $commentStart; $i <= $commentEnd; $i++) { + for ($i = $tokens[$commentEnd]['comment_opener']; $i <= $commentEnd; $i++) { $phpcsFile->fixer->replaceToken($i, ''); } } @@ -161,6 +157,7 @@ public function process(File $phpcsFile, $stackPtr) return; } + $commentStart = $tokens[$commentEnd]['comment_opener']; foreach ($tokens[$commentStart]['comment_tags'] as $tag) { // This is a file comment, not a function comment. if ($tokens[$tag]['content'] === '@file') { From 5e400396be7c8cd46f796920814a9b2f59153db3 Mon Sep 17 00:00:00 2001 From: Claudiu Cristea Date: Sat, 28 Sep 2024 21:14:18 +0200 Subject: [PATCH 4/6] Use placeholder in message --- coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php b/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php index ccd6e334..61f95899 100644 --- a/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php +++ b/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php @@ -112,7 +112,7 @@ public function process(File $phpcsFile, $stackPtr) } } else if (in_array($methodName, $this->commentProhibitedFunctions, true) === true) { // Method prohibited to have docblock. - $fix = $phpcsFile->addFixableError("It's forbidden to document $methodName function", $stackPtr, 'DocProhibited'); + $fix = $phpcsFile->addFixableError("It's forbidden to document %s function", $stackPtr, 'ForbiddenFunction', [$methodName]); if ($fix === true) { for ($i = $tokens[$commentEnd]['comment_opener']; $i <= $commentEnd; $i++) { $phpcsFile->fixer->replaceToken($i, ''); From e0ef19b911d252fef28421fc77652d59ebe70c2a Mon Sep 17 00:00:00 2001 From: Claudiu Cristea Date: Sat, 28 Sep 2024 21:15:14 +0200 Subject: [PATCH 5/6] Tests --- .../Commenting/FunctionCommentUnitTest.inc | 11 +++ .../FunctionCommentUnitTest.inc.fixed | 5 + .../Commenting/FunctionCommentUnitTest.php | 93 ++++++++++--------- 3 files changed, 63 insertions(+), 46 deletions(-) diff --git a/tests/Drupal/Commenting/FunctionCommentUnitTest.inc b/tests/Drupal/Commenting/FunctionCommentUnitTest.inc index b005dd4c..44a3881d 100644 --- a/tests/Drupal/Commenting/FunctionCommentUnitTest.inc +++ b/tests/Drupal/Commenting/FunctionCommentUnitTest.inc @@ -3,6 +3,7 @@ /** * @file * Some function comment tests. + * phpcs:set Drupal.Commenting.FunctionComment commentProhibitedFunctions[] docblock_is_not_allowed */ /** @@ -976,3 +977,13 @@ function return_some_array(): array { }); return []; } + +/** + * Don't document this function. + * + * @return bool + * Something. + */ +function docblock_is_not_allowed(): bool { + return TRUE; +} diff --git a/tests/Drupal/Commenting/FunctionCommentUnitTest.inc.fixed b/tests/Drupal/Commenting/FunctionCommentUnitTest.inc.fixed index 817400ca..b97d56d1 100644 --- a/tests/Drupal/Commenting/FunctionCommentUnitTest.inc.fixed +++ b/tests/Drupal/Commenting/FunctionCommentUnitTest.inc.fixed @@ -3,6 +3,7 @@ /** * @file * Some function comment tests. + * phpcs:set Drupal.Commenting.FunctionComment commentProhibitedFunctions[] docblock_is_not_allowed */ /** @@ -1002,3 +1003,7 @@ function return_some_array(): array { }); return []; } + +function docblock_is_not_allowed(): bool { + return TRUE; +} diff --git a/tests/Drupal/Commenting/FunctionCommentUnitTest.php b/tests/Drupal/Commenting/FunctionCommentUnitTest.php index b32119ce..4a471a47 100644 --- a/tests/Drupal/Commenting/FunctionCommentUnitTest.php +++ b/tests/Drupal/Commenting/FunctionCommentUnitTest.php @@ -23,55 +23,56 @@ protected function getErrorList(string $testFile): array switch ($testFile) { case 'FunctionCommentUnitTest.inc': return [ - 12 => 1, - 14 => 1, - 33 => 1, - 43 => 1, - 53 => 1, - 62 => 1, - 71 => 1, - 78 => 1, - 87 => 1, - 92 => 1, - 101 => 1, - 113 => 1, - 126 => 2, - 147 => 1, - 148 => 2, - 187 => 1, - 195 => 1, - 205 => 1, - 215 => 1, + 13 => 1, + 15 => 1, + 34 => 1, + 44 => 1, + 54 => 1, + 63 => 1, + 72 => 1, + 79 => 1, + 88 => 1, + 93 => 1, + 102 => 1, + 114 => 1, + 127 => 2, + 148 => 1, + 149 => 2, + 188 => 1, + 196 => 1, + 206 => 1, 216 => 1, - 225 => 3, - 233 => 1, - 235 => 1, - 237 => 1, - 248 => 1, - 250 => 1, - 252 => 1, - 254 => 1, - 256 => 1, - 298 => 1, - 308 => 1, - 311 => 1, - 321 => 1, - 324 => 1, - 334 => 1, - 345 => 1, - 357 => 1, - 360 => 1, - 371 => 1, - 389 => 2, + 217 => 1, + 226 => 3, + 234 => 1, + 236 => 1, + 238 => 1, + 249 => 1, + 251 => 1, + 253 => 1, + 255 => 1, + 257 => 1, + 299 => 1, + 309 => 1, + 312 => 1, + 322 => 1, + 325 => 1, + 335 => 1, + 346 => 1, + 358 => 1, + 361 => 1, + 372 => 1, 390 => 2, - 401 => 1, - 414 => 1, - 416 => 1, - 426 => 2, + 391 => 2, + 402 => 1, + 415 => 1, + 417 => 1, 427 => 2, - 538 => 1, - 540 => 1, - 941 => 1, + 428 => 2, + 539 => 1, + 541 => 1, + 942 => 1, + 987 => 1, ]; case 'FunctionCommentUnitTest.1.inc': return []; From b3cedcc2288f9b0c8760382a41aefa4342e68bde Mon Sep 17 00:00:00 2001 From: Claudiu Cristea Date: Sat, 28 Sep 2024 21:26:51 +0200 Subject: [PATCH 6/6] Better code --- coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php b/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php index 61f95899..87fbf5d5 100644 --- a/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php +++ b/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php @@ -112,7 +112,7 @@ public function process(File $phpcsFile, $stackPtr) } } else if (in_array($methodName, $this->commentProhibitedFunctions, true) === true) { // Method prohibited to have docblock. - $fix = $phpcsFile->addFixableError("It's forbidden to document %s function", $stackPtr, 'ForbiddenFunction', [$methodName]); + $fix = $phpcsFile->addFixableError("It's forbidden to document %s function", $stackPtr, 'ForbiddenDocBlock', [$methodName]); if ($fix === true) { for ($i = $tokens[$commentEnd]['comment_opener']; $i <= $commentEnd; $i++) { $phpcsFile->fixer->replaceToken($i, '');