Conversation
When a block comment is multi-line, the first `T_COMMENT` token will start with the `/*`, but `T_COMMENT` tokens which are part of the block comment on subsequent lines will include the indentation in the `T_COMMENT` token.
This makes these tokens more complex to deal with in sniffs, especially for indentation calculations.
The `PEAR.Functions.FunctionDeclaration` sniff did not take the possibility of a multi-line block comment being part of the signature of a multi-line function declaration into account (at all).
This also affected, by extension, the `Squiz.Functions.MultiLineFunctionDeclaration` sniff and would cause a fixer conflict of the sniff with itself.
This commit fixes this.
Includes extensive tests.
Note - there are two caveats to the fix:
1. If subsequent lines in a block comment are not prefixed with a `*`, the indentation fix will not be precise, but will be a best-effort "indent needs to be the same or larger than the expected indent".
2. Like for all sniffs, lines containing PHPCS annotations will be ignored unless the `--ignore-annotations` CLI flag is used.
That also applies to these lines when they are part of a multi-line block comment.
Fixes 1368
4 tasks
anomiex
approved these changes
Mar 2, 2026
jrfnl
deleted the
feature/1368/squiz-multilinefunctiondeclaration-improve-comment-handling
branch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
When a block comment is multi-line, the first
T_COMMENTtoken will start with the/*, butT_COMMENTtokens which are part of the block comment on subsequent lines will include the indentation in theT_COMMENTtoken. This makes these tokens more complex to deal with in sniffs, especially for indentation calculations.The
PEAR.Functions.FunctionDeclarationsniff did not take the possibility of a multi-line block comment being part of the signature of a multi-line function declaration into account (at all). This also affected, by extension, theSquiz.Functions.MultiLineFunctionDeclarationsniff and would cause a fixer conflict of the sniff with itself.This commit fixes this.
Includes extensive tests.
Note - there are two caveats to the fix:
*, the indentation fix will not be precise, but will be a best-effort "indent needs to be the same or larger than the expected indent".--ignore-annotationsCLI flag is used. That also applies to these lines when they are part of a multi-line block comment.Fixes #1368
Suggested changelog entry
PEAR.Functions.FunctionDeclaration: the indentation for subsequent lines in multi-line block comments would be incorrectly determined, leading to false positives and resulting in a fixer conflict when runningphpcbf.This also affected the
Squiz.Functions.MultiLineFunctionDeclarationsniff by extension.