Skip to content

change logic phpDoc comment sniff #38

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ZhukV merged 2 commits into from
Jun 25, 2025
Merged

change logic phpDoc comment sniff #38

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
918a696
change logic phpDoc comment sniff
Lassombria Jun 16, 2025
cb9044d
Merge branch 'master' into update-php-doc-sniff
Lassombria Jun 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 9 additions & 52 deletions src/PhpCs/FiveLab/Sniffs/Commenting/ProhibitedDocCommentsSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ public function process(File $phpcsFile, mixed $stackPtr): void
{
$tokens = $phpcsFile->getTokens();
$commentToken = $tokens[$stackPtr];
$closePtr = $phpcsFile->findNext(T_DOC_COMMENT_CLOSE_TAG, $stackPtr + 1);

$possiblyDeclaration = $phpcsFile->findNext([
T_CLASS, T_INTERFACE, T_TRAIT, T_FUNCTION,
Expand All @@ -40,65 +41,21 @@ public function process(File $phpcsFile, mixed $stackPtr): void
return;
}

$varPtr = $phpcsFile->findNext(T_VARIABLE, $commentToken['comment_closer'] + 1, local: true);
$hasMetaTag = false;

if ($varPtr) {
$commentTokenPtr = $phpcsFile->findNext(T_DOC_COMMENT_TAG, ($stackPtr + 1), $commentToken['comment_closer'], local: true);

if (false === $commentTokenPtr) {
$phpcsFile->addError(
'PHPDoc comment can contains only @var here.',
$stackPtr,
ErrorCodes::PHPDOC_NOT_ALLOWED
);

return;
for ($i = $stackPtr + 1; $i < $closePtr; $i++) {
if ($tokens[$i]['code'] === T_DOC_COMMENT_TAG) {
$hasMetaTag = true;
break;
}
}

$isOnlyVarTag = $this->isHasOnlyVarTag($phpcsFile, $stackPtr, $commentToken['comment_closer'], $tokens);

if (true === $isOnlyVarTag) {
return;
}

$phpcsFile->addError(
'PHPDoc comment is not allowed here.',
$stackPtr,
ErrorCodes::PHPDOC_NOT_ALLOWED
);
}

/**
* Check has T_DOC_COMMENT_TAG another tags
*
* @param File $phpcsFile
* @param int $startPtr
* @param int $endPtr
* @param array<int, mixed> $tokens
*
* @return bool|null
*/
private function isHasOnlyVarTag(File $phpcsFile, int $startPtr, int $endPtr, array $tokens): ?bool
{
$commentTokenPtr = $phpcsFile->findNext(T_DOC_COMMENT_TAG, ($startPtr + 1), $endPtr);

if (false === $commentTokenPtr) {
return null;
}

if ($commentTokenPtr && $tokens[$commentTokenPtr]['content'] !== '@var') {
if (!$hasMetaTag) {
$phpcsFile->addError(
\sprintf('PHPDoc comment tag %s is not allowed here.', $tokens[$commentTokenPtr]['content']),
$commentTokenPtr,
'PHPDoc must contain at least one meta tag like @param, @return, etc.',
$stackPtr,
ErrorCodes::PHPDOC_NOT_ALLOWED
);

return false;
}

$this->isHasOnlyVarTag($phpcsFile, $commentTokenPtr, $endPtr, $tokens);

return true;
}
}
1 change: 1 addition & 0 deletions src/PhpCs/FiveLab/Sniffs/Namespace/NamespaceSniff.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@ private function getExpectedNamespace(File $phpcsFile): ?string
* @param string $composerJsonPath
*
* @return array<mixed>
*
* @throws \JsonException
*/
private function loadComposerJson(string $composerJsonPath): array
Expand Down
3 changes: 3 additions & 0 deletions src/PhpStan/MethodCallConsistencyRule.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ public function processNode(Node $node, Scope $scope): array
* @param Scope $scope
*
* @return list<IdentifierRuleError>
*
* @throws ShouldNotHappenException
*/
private function checkStaticCall(Node\Expr\StaticCall $node, Scope $scope): array
Expand Down Expand Up @@ -96,6 +97,7 @@ private function checkStaticCall(Node\Expr\StaticCall $node, Scope $scope): arra
* @param Scope $scope
*
* @return list<IdentifierRuleError>
*
* @throws ShouldNotHappenException
*/
private function checkInstanceCall(Node\Expr\MethodCall $node, Scope $scope): array
Expand Down Expand Up @@ -130,6 +132,7 @@ private function checkInstanceCall(Node\Expr\MethodCall $node, Scope $scope): ar
* @param Scope $scope
*
* @return list<IdentifierRuleError>
*
* @throws ShouldNotHappenException|MissingMethodFromReflectionException
*/
private function checkNativeMethodCall(Node\Expr\StaticCall $node, Scope $scope): array
Expand Down
14 changes: 5 additions & 9 deletions tests/PhpCs/FiveLab/Sniffs/Commenting/ProhibitedDocCommentsSniffTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,27 +33,23 @@ public static function provideDataSet(): array
'wrong' => [
__DIR__.'/Resources/prohibited-doc-comments/wrong.php',
[
'message' => 'PHPDoc comment is not allowed here.',
'message' => 'PHPDoc must contain at least one meta tag like @param, @return, etc.',
'source' => 'FiveLab.Commenting.ProhibitedDocComments.PhpDocNotAllowed',
],
[
'message' => 'PHPDoc comment can contains only @var here.',
'message' => 'PHPDoc must contain at least one meta tag like @param, @return, etc.',
'source' => 'FiveLab.Commenting.ProhibitedDocComments.PhpDocNotAllowed',
],
[
'message' => 'PHPDoc comment can contains only @var here.',
'message' => 'PHPDoc must contain at least one meta tag like @param, @return, etc.',
'source' => 'FiveLab.Commenting.ProhibitedDocComments.PhpDocNotAllowed',
],
[
'message' => 'PHPDoc comment tag @return is not allowed here.',
'message' => 'PHPDoc must contain at least one meta tag like @param, @return, etc.',
'source' => 'FiveLab.Commenting.ProhibitedDocComments.PhpDocNotAllowed',
],
[
'message' => 'PHPDoc comment can contains only @var here.',
'source' => 'FiveLab.Commenting.ProhibitedDocComments.PhpDocNotAllowed',
],
[
'message' => 'PHPDoc comment is not allowed here.',
'message' => 'PHPDoc must contain at least one meta tag like @param, @return, etc.',
'source' => 'FiveLab.Commenting.ProhibitedDocComments.PhpDocNotAllowed',
],
],
Expand Down
4 changes: 4 additions & 0 deletions tests/PhpCs/FiveLab/Sniffs/Commenting/Resources/prohibited-doc-comments/success.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,10 @@ class Some {
* @var string
*/
private string $foo;

/**
* @see some456
*/
public const FOO = 'foo';
const BAR = 'bar';

Expand Down
6 changes: 0 additions & 6 deletions tests/PhpCs/FiveLab/Sniffs/Commenting/Resources/prohibited-doc-comments/wrong.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,12 +22,6 @@ public function bar(): void
$foo2 = 'bar';
};

/**
* @var int $bar
* @return string
*/
$bar = 1;

/**
* Some comment
*/
Expand Down