PHP_CodeSniffer
PHP_CodeSniffer copied to clipboard
Not possible to not document only some parameters
Describe the bug
40 | ERROR | Doc comment for parameter $debug does not match actual
| | variable name $css
Code sample
/**
* @param bool $debug
* If this is `true`, an exception will be thrown if invalid CSS is encountered.
* Otherwise the parser will try to do the best it can.
*/
public function __construct(string $css, bool $debug)
{
// ...
}
Custom ruleset
<?xml version="1.0" encoding="UTF-8"?>
<ruleset name="Coding Standard">
<description>
This standard requires PHP_CodeSniffer >= 3.2.0.
</description>
<config name="installed_paths" value="../../slevomat/coding-standard"/>
<!-- The complete PSR-12 ruleset -->
<rule ref="PSR12"/>
<!-- Arrays -->
<rule ref="Generic.Arrays.DisallowLongArraySyntax"/>
<rule ref="Squiz.Arrays.ArrayBracketSpacing"/>
<rule ref="Squiz.Arrays.ArrayDeclaration.NoCommaAfterLast"/>
<!-- Classes -->
<rule ref="Generic.Classes.DuplicateClassName"/>
<rule ref="Squiz.Classes.ClassFileName"/>
<rule ref="Squiz.Classes.DuplicateProperty"/>
<rule ref="Squiz.Classes.LowercaseClassKeywords"/>
<rule ref="Squiz.Classes.SelfMemberReference"/>
<!-- Code analysis -->
<rule ref="Generic.CodeAnalysis.EmptyStatement"/>
<rule ref="Generic.CodeAnalysis.AssignmentInCondition"/>
<rule ref="Generic.CodeAnalysis.ForLoopShouldBeWhileLoop"/>
<rule ref="Generic.CodeAnalysis.ForLoopWithTestFunctionCall"/>
<rule ref="Generic.CodeAnalysis.JumbledIncrementer"/>
<rule ref="Generic.CodeAnalysis.UnconditionalIfStatement"/>
<rule ref="Generic.CodeAnalysis.UnnecessaryFinalModifier"/>
<rule ref="Generic.CodeAnalysis.UnusedFunctionParameter"/>
<rule ref="Generic.CodeAnalysis.UselessOverridingMethod"/>
<!-- Commenting -->
<rule ref="Generic.Commenting.Fixme"/>
<rule ref="Generic.Commenting.Todo"/>
<rule ref="PEAR.Commenting.InlineComment"/>
<rule ref="Squiz.Commenting.DocCommentAlignment"/>
<rule ref="Squiz.Commenting.EmptyCatchComment"/>
<rule ref="Squiz.Commenting.FunctionComment">
<exclude-pattern>*/tests/*</exclude-pattern>
<!-- Allow no comment for self-describing parameter and exception class names. -->
<exclude name="Squiz.Commenting.FunctionComment.MissingParamComment"/>
<exclude name="Squiz.Commenting.FunctionComment.EmptyThrows"/>
<!-- Allow "int" rather than "integer", etc., in PHPDoc. -->
<exclude name="Squiz.Commenting.FunctionComment.IncorrectParamVarName"/>
<exclude name="Squiz.Commenting.FunctionComment.InvalidReturn"/>
<!-- Allow "@return" to be omitted (for methods which do not return a value). -->
<exclude name="Squiz.Commenting.FunctionComment.MissingReturn"/>
<!-- Allow parameter type, name and comment not all vertically aligned. -->
<exclude name="Squiz.Commenting.FunctionComment.SpacingAfterParamType"/>
<exclude name="Squiz.Commenting.FunctionComment.SpacingAfterParamName"/>
<!-- Allow parameter and exception descriptions which are not full sentences. -->
<exclude name="Squiz.Commenting.FunctionComment.ParamCommentNotCapital"/>
<exclude name="Squiz.Commenting.FunctionComment.ParamCommentFullStop"/>
<exclude name="Squiz.Commenting.FunctionComment.ThrowsNotCapital"/>
<exclude name="Squiz.Commenting.FunctionComment.ThrowsNoFullStop"/>
<!-- Allow `object{...}` type hints. -->
<exclude name="Squiz.Commenting.FunctionComment.MissingParamTag"/>
<exclude name="Squiz.Commenting.FunctionComment.MissingParamName"/>
<exclude name="Squiz.Commenting.FunctionComment.IncorrectTypeHint"/>
</rule>
<rule ref="Squiz.Commenting.FunctionCommentThrowTag">
<!-- If we want to document exceptions thrown by called methods for a method that also throws its own
exceptions, this sniff simply does not work. -->
<exclude name="Squiz.Commenting.FunctionCommentThrowTag.WrongNumber"/>
</rule>
<rule ref="Squiz.Commenting.PostStatementComment"/>
<!-- Control structures -->
<rule ref="PEAR.ControlStructures.ControlSignature"/>
<!-- Debug -->
<rule ref="Generic.Debug.ClosureLinter"/>
<!-- Files -->
<rule ref="Generic.Files.OneClassPerFile"/>
<rule ref="Generic.Files.OneInterfacePerFile"/>
<rule ref="Generic.Files.OneObjectStructurePerFile"/>
<rule ref="Zend.Files.ClosingTag"/>
<!-- Formatting -->
<rule ref="Generic.Formatting.NoSpaceAfterCast"/>
<rule ref="PEAR.Formatting.MultiLineAssignment"/>
<!-- Functions -->
<rule ref="Generic.Functions.CallTimePassByReference"/>
<rule ref="Squiz.Functions.FunctionDuplicateArgument"/>
<rule ref="Squiz.Functions.GlobalFunction"/>
<!-- Metrics -->
<rule ref="Generic.Metrics.CyclomaticComplexity"/>
<rule ref="Generic.Metrics.NestingLevel"/>
<!-- Naming conventions -->
<rule ref="Generic.NamingConventions.ConstructorName"/>
<rule ref="PEAR.NamingConventions.ValidClassName"/>
<!-- Objects -->
<rule ref="Squiz.Objects.ObjectMemberComma"/>
<!-- Operators -->
<rule ref="Squiz.Operators.IncrementDecrementUsage"/>
<rule ref="Squiz.Operators.ValidLogicalOperators"/>
<!-- PHP -->
<rule ref="Generic.PHP.BacktickOperator"/>
<rule ref="Generic.PHP.CharacterBeforePHPOpeningTag"/>
<rule ref="Generic.PHP.DeprecatedFunctions"/>
<rule ref="Generic.PHP.DisallowAlternativePHPTags"/>
<rule ref="Generic.PHP.DisallowShortOpenTag"/>
<rule ref="Generic.PHP.DiscourageGoto"/>
<rule ref="Generic.PHP.ForbiddenFunctions"/>
<rule ref="Generic.PHP.NoSilencedErrors"/>
<rule ref="Squiz.PHP.CommentedOutCode">
<properties>
<property name="maxPercentage" value="70"/>
</properties>
</rule>
<rule ref="Squiz.PHP.DisallowMultipleAssignments"/>
<rule ref="Squiz.PHP.DisallowSizeFunctionsInLoops"/>
<rule ref="Squiz.PHP.DiscouragedFunctions"/>
<rule ref="Squiz.PHP.Eval"/>
<rule ref="Squiz.PHP.GlobalKeyword"/>
<rule ref="Squiz.PHP.Heredoc"/>
<rule ref="Squiz.PHP.InnerFunctions"/>
<rule ref="Squiz.PHP.LowercasePHPFunctions"/>
<rule ref="Squiz.PHP.NonExecutableCode"/>
<!-- Scope -->
<rule ref="Squiz.Scope.MemberVarScope"/>
<rule ref="Squiz.Scope.StaticThisUsage"/>
<!--Strings-->
<rule ref="Squiz.Strings.DoubleQuoteUsage"/>
<!-- Whitespace -->
<rule ref="PEAR.WhiteSpace.ObjectOperatorIndent"/>
<rule ref="PEAR.WhiteSpace.ScopeClosingBrace"/>
<rule ref="Squiz.WhiteSpace.CastSpacing"/>
<rule ref="Squiz.WhiteSpace.LogicalOperatorSpacing"/>
<rule ref="Squiz.WhiteSpace.OperatorSpacing">
<properties>
<property name="ignoreNewlines" value="true"/>
</properties>
</rule>
<rule ref="Squiz.WhiteSpace.PropertyLabelSpacing"/>
<rule ref="Squiz.WhiteSpace.SemicolonSpacing"/>
</ruleset>
To reproduce Steps to reproduce the behavior:
- Create a file called
test.phpwith the code sample above... - Run
phpcs test.php ... - See error message displayed
40 | ERROR | Doc comment for parameter $debug does not match actual
| | variable name $css
Expected behavior No error. We have specifically allowed in the XML settings for not having superfluous DocBlock content that merely repeats what's in the function signature. Even if there was an error reported, it should be accurate and not apparently have misidentified the parameter in the DocBlock.
Versions (please complete the following information):
- OS: Windows 10
- PHP: 7.3.11
- PHPCS: 3.6.2 (via PHIVE)
- Standard: PSR4
Additional context See above.