Php_codesniffer: Subsniffs undocumented and undiscoverable

[Bilge]

I've become aware that sniffs such as Squiz.Commenting.FunctionComment contain many sub-sniffs, including, but not limited to:

• Squiz.Commenting.FunctionComment.MissingParamTag
• Squiz.Commenting.FunctionComment.ParamCommentFullStop
• Squiz.Commenting.FunctionComment.MissingReturn
• Squiz.Commenting.FunctionComment.ParamCommentNotCapital
• Squiz.Commenting.FunctionComment.ThrowsNotCapital
• Squiz.Commenting.FunctionComment.EmptyThrows
• Squiz.Commenting.FunctionComment.IncorrectParamVarName
• Squiz.Commenting.FunctionComment.InvalidReturn

Not only are none of these discoverable, none of their behaviours appear to be documented and they barely even appear in repository code searches. I am absolutely baffled as to where these sniffs are declared let alone how anyone is supposed to know they exist or understand what they should do.

Where can I find a complete list of sniffs and subsniffs and documentation of their behaviour? Note that the output of phpcs -e --standard=Squiz completely hides the presence of sub-sniffs.

[jrfnl]

Those are not subsniffs, but error codes.

While incomplete, quite a few sniffs do actually have documentation which you can see by running phpcs --standard=Squiz --generator=Text.

Unfortunately, it appears that the Squiz.Commenting.FunctionComment sniff does not have a documentation file, so for that one you'd have to look at the actual sniff code to see what errors it throws.

I'm guessing that PRs which add more documentation would be welcomed ;-)

The documentation takes the form of a SniffNameStandard.xml file in the Docs directory of a standard.

[Bilge]

I don't understand how error codes can be used as configuration nodes. That seems really bizarre.

[gsherwood]

I don't understand how error codes can be used as configuration nodes. That seems really bizarre.

I'm not sure what you are asking about here, but the general idea of PHPCS is that there are sniff classes and each produces one or more error messages. The error messages all have error codes, which allows you to take that code and change things about the message (text, severity etc). Examples are in here: https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-Ruleset

Sniff classes have properties, which change the behaviour of the sniff. These are listed here: https://github.com/squizlabs/PHP_CodeSniffer/wiki/Customisable-Sniff-Properties

[jrfnl]

Related #1926

[gsherwood]

Do you need any more help on this issue or have I explained things well enough?

[Bilge]

I was writing a reply but then was so confounded by how you can be so unclear as to how deficient the current documentation is that I got bored and put it on hold indefinitely. I can try again if you want.

[gsherwood]

I can try again if you want.

Up to you mate. You're making it hard to give up my time to be helpful.

[ondrejmirtes]

@Bilge This is open-source. Roll up your sleeves and offer help by sending PR with improvement.

[Bilge]

@ondrejmirtes After you.

[vladyslavstartsev]

@Bilge

@ondrejmirtes After you.

hey man, @ondrejmirtes is actually a guy who build a super useful tool called PHPstan.
so he made his PRs, now it's your turn :wink:

[Bilge]

@gsherwood I have some more time for this now.

This is a problem of sniff name discoverability. There should be complete, unabridged documentation of all sniffs and so-called subsnifffs. The closest thing we have is Customisable Sniff Properties, but this is far from complete (not to mention, this document is one of the last in the Wiki index).

Compare this to PHP Coding Standards Fixer, which not only documents every single sniff and its configuration, but does so right in the main readme where it cannot be easily overlooked.

With PHP_CodeSniffer the only way to discover the deep subsniffs is to include everything, be bitten by them, and then selectively disable them as required. This is not a good way to configure the software.

• For the use-case where one wishes to evaluate all the rules and selectively whitelist some, we cannot use this method.
• For the use-case where one wishes to include a rule set and selectively disable rules in advance of running the program, we cannot use this method.

Therefore, to improve discoverability of sniff names we must improve the documentation so it is complete. Is this clear now?

[jrfnl]

@Bilge There's recently been a discussion about this in https://github.com/squizlabs/PHP_CodeSniffer/pull/2345. Would what is proposed there solve it in your opinion ? and would you be willing to contribute to that project by updating existing documentation and adding missing docs ?

[Bilge]

@jrfnl Potentially, but that 4+ level deep expanding menu system is awful, not to mention completely dysfunctional on mobile. The important thing, however, is that the content is there, which it still is not in the demo URL. To be clear, I don't require there to be a separate documentation system; just that the information about _all_ the sniffs is available somewhere in some form.

[jrfnl]

@Bilge I didn't mean the PR itself, I meant the discussion below it, i.e. improve the existing SniffNameStandard.xml documentation files (and add these for the sniffs missing them) and use those as a basis to automatically generate the documentation for use in the wiki. See: https://github.com/squizlabs/PHP_CodeSniffer/pull/2345#issuecomment-453264115