diff --git a/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php b/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php index 8db59805..87fbf5d5 100644 --- a/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php +++ b/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php @@ -24,6 +24,13 @@ class FunctionCommentSniff implements Sniff { + /** + * List of methods that are prohibited to have docblock. + * + * @var array + */ + public $commentProhibitedFunctions = []; + /** * A map of invalid data types to valid ones for param and return documentation. * @@ -94,13 +101,24 @@ public function process(File $phpcsFile, $stackPtr) break; } - // 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; + } + } 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, 'ForbiddenDocBlock', [$methodName]); + if ($fix === true) { + for ($i = $tokens[$commentEnd]['comment_opener']; $i <= $commentEnd; $i++) { + $phpcsFile->fixer->replaceToken($i, ''); + } + } + return; } 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 [];