PHP_CodeSniffer icon indicating copy to clipboard operation
PHP_CodeSniffer copied to clipboard

Not possible to not document only some parameters

Open JakeQZ opened this issue 2 years ago • 0 comments

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:

  1. Create a file called test.php with the code sample above...
  2. Run phpcs test.php ...
  3. 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.

JakeQZ avatar Dec 23 '21 23:12 JakeQZ