Php_codesniffer: Is there a documentation of just all sniffs and what they do, possibly including parameters?

[afoeder]

I know phpcs -e but I miss an explanation what each sniff does; respectively I miss a documentation in the wiki or something like this.
If there isn't I might try to build something which extracts the explanation from the well-written doc block:

<?php
/**
 * Makes sure that any use of double quotes strings are warranted.
 *
 * @author    Greg Sherwood <[email protected]>
 * @copyright 2006-2015 Squiz Pty Ltd (ABN 77 084 670 600)
 * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
 */

[chadxz]

Example from another tool: https://eslint.org/docs/rules/ shows all "stock" rules as well as examples of allowed and not allowed for each.

[gsherwood]

Some sniffs have docs in a Docs folder, which can be printed by using the --generator CLI argument. But in general, no, there is no place to get full documentation about all the sniffs. I've never had time to finish a project like that.

You wont be able to create documentation from just parsing doc blocks because PHPCS sniffs are a collection of sniff codes, each checking something different. You need to actually go through the sniff and check the error messages, then document each code and what it does. It's a huge job.

[afoeder]

@gsherwood IMO the doc comments will suffice for a first draft at least?
Have a look at my WIP at https://github.com/afoeder/PHP_CodeSniffer/blob/feature/sniff-reference-builder/scripts/build-sniff-reference.php which will already (at this exact state) render something like the following (see https://gist.github.com/afoeder/0712c5fad9b517806f53c0b461a49cf1 for a complete output):

Squiz.Debug.JSLint

Runs jslint.js on the file.

declared in PHP_CodeSniffer\Standards\Squiz\Sniffs\Debug\JSLintSniff

Squiz.Debug.JavaScriptLint

Runs JavaScript Lint on the file.

declared in PHP_CodeSniffer\Standards\Squiz\Sniffs\Debug\JavaScriptLintSniff

PSR1.Classes.ClassDeclaration

Checks the declaration of the class is correct.

declared in
PHP_CodeSniffer\Standards\PSR1\Sniffs\Classes\ClassDeclarationSniff

PSR1.Files.SideEffects

Ensures a file declares new symbols and causes no other side effects, or
executes logic with side effects, but not both.

declared in PHP_CodeSniffer\Standards\PSR1\Sniffs\Files\SideEffectsSniff

---

Still to do is to group and order it by standard, category and sniff name, but I think that'd be helpful already for browsing. In the future this can be augmented by additional information like accepted parameters etc, maybe again with help of annotations, e.g. by Doctrine's AnnotationReader.

WDYT?

[gsherwood]

WDYT?

Thanks for generating that list, but I wouldn't publish it in the PHPCS docs because I know the content isn't good enough, which means I'll get people asking for corrections and clarifications.

If I'm going to publish docs, they need to be accurate and I know the comments are not clear enough as to what the sniffs actually do and aren't able to show just how many checks are actually performed.

The sort of docs I want to produce have information about the checks + code examples where appropriate. You can see an example by running phpcs --standard=PEAR --generator=text.

[gsherwood]

Closing this to roll the discussion into one idea. There was already #1603 for this, but I forgot about ti.

[igorsantos07]

Oh my... I'm pulling out my hair trying to find this exact list of rules. Clicked around the wiki a lot of times, googled a couple of rules, and only found samples or tutorials. After understanding the internal name for those rules is "sniff", I ended up here.

I've already worked a bit with other linters, such as ESLint which got cited above... It's very easy to understand what you want to change in your ruleset and whatnot, but it's very surprising to see such an old tool like PHPCS not having _anything_ like that.

I'm pretty sure we all know that _some_ documentation is better than _no documentation at all_.
Please, reconsider the idea! Move forward with @afoeder's idea. It's crazy that during all this time there's no single, human-readable list of sniffs, and not even suggestions on what to do in case you want to know which rules are available. "Sniffing" through PHPCS source-code is the worst suggestion you can give if we all want linters to be wide-spread in the community.

After all, now I understand why PHPCS is much less used than tools like ESLint. Because it's not really user-friendly :(

[gsherwood]

it's very surprising to see such an old tool like PHPCS not having _anything_ like that

I'm one person with a very full-time job + 2 kids + I don't make any money from PHPCS. I get some great contributions, but almost none have anything to do with documentation. Anything I do accept into the code needs to be kept up-to-date, and I know I barely have enough time to work on PHPCS bugs and feature as it is.

This is why.

I could really use help. And not one-off help. I need consistent help to maintain a project that has grown bigger and bigger over the years.

[igorsantos07]

Sad story of many open source projects, I completely understand your reasons.

I only still have a hard time getting why no documentation is better than "documented but noted as could be outdated". I mean, are new styling rules created every time? And if they included, couldn't you simply request a doc update as well?

It might just be my own taste, but it feels much more common to have to customize a rules file, and this is very out of place with other linters... And I've used others before coming to PHPCS 🤷🏼‍♂️

[XedinUnknown]

Any update to this? @gsherwood, did you get the help you needed?

[mycarrysun]

2 years later and just finding this thread...I do have to agree with the others on this coming into this library and finding a lot of use out of it but honestly the documentation is missing an entire section not having any of the rules and their descriptions. It has been hard for me to find built-in rules and so I have opted to just use the Slevomat coding standard since all of their rules are documented. The built-in rules that I am using are just ones that I found randomly and found out they worked how I wanted but there was no documentation (and there is no way I would be able to find out the parameters to use for configurable rules).

I totally understand your concerns about maintenance but there is an easy solution to that - require all PRs to have changes to the documentation of the rules that they touch. This is done in many other repos because of the same concerns that you have.

I have found a lot of value out of this linter but not having documentation on the rules could be a barrier on me using it long-term. I have a feeling that could also be a barrier for others and could prevent more meaningful contributions to the project.

[jrfnl]

Just for anyone coming across this thread: a lot of sniffs have documentation on what the sniff looks for, including code samples.

To view it, use:

phpcs --standard=PSR12 --generator=text

You can, of course, replace the standard name PSR12 with the name of any other standard.
Along the same lines, if you don't like reading this on the command line, you can replace text with html or markdown and pipe the output to a file to view it with mark-up.

[mycarrysun]

@jrfnl would it be terribly hard to have a loop that generates an .md file with the output of the command you mentioned? Seems like this could be a nice way to maintain everything - as long as each PR is enforcing the update of the generated text when necessary seems like it could be pretty straightforward.

[jrfnl]

@mycarrysun I'm not sure what you mean ? You can pipe the output of the command I mention to an md file. Or do you mean to add to the docs here ? If so, that's not my decision.

I did open a PR a while back to add a CI check for all sniffs being accompanied by tests and a doc file, but that got closed: https://github.com/squizlabs/PHP_CodeSniffer/pull/2872

[MasterOdin]

To add to this thread, per @gsherwood's comment in https://github.com/squizlabs/PHP_CodeSniffer/issues/2489#issuecomment-491682505:

Thanks for taking a look at this. I've put any documentation changes on hold as there is a concurrent project about product documentation ongoing where I work and I will probably use the format selected to continue PHPCS docs. This will include how the docs are written and where they are hosted. They will definitely not be XML, so I suspect the entire XML format will disappear in favour of an easier syntax to work with (I don't know what it is yet).

As I stated in #2489, I am happy to help with the documentation effort, but I'd rather not spend the time doing it in a format that the author considers potentially dead nor as some side project split off from PHPCS as that would just make maintaining it (and gaining traction) all the more difficult.

[mycarrysun]

Or do you mean to add to the docs here ?

Yes, this is what I meant - so that devs don't need to know how to loop through or even that the command argument is --generator=text.

In the meantime, it might be nice to make a prominent note of the --generator=text option in the docs so that it is more visible to newcomers.

[jrfnl]

I'd rather not spend the time doing it in a format that the author considers potentially dead nor as some side project split off from PHPCS as that would just make maintaining it (and gaining traction) all the more difficult.

I hear you. All the same, I'd been playing with some ideas around this for a while, just haven't had the time to action it. For now, I've written up the rough idea I have: https://github.com/PHPCSStandards/PHPCSStandards.github.io/issues/1