Php_codesniffer: Improve PHPCS documentation

[Basje]

In response to this message on Reddit.

I haven't got loads of time to help, but if more people join in then we could make some steps to proper documentation!

@gsherwood: you mentioned that you write documentation professionally. Could you set up some guidelines for us laymen on how to write quality documentation? Links are fine too.

I will post this on Reddit as well, see if we can get some people to join this effort.

[jrfnl]

Just a thought: if all sniffs had proper XML docs associated with them (example), would it not be possible to auto-generate a documentation site based on those ?

This will require the docs to be improved or even added for a lot of sniffs.

It may also require the docs XML standard to be extended and formalized.

One of the things I've been missing, for instance, would be to have a block per error code and to have those error codes as nodes or attributes in the XML.
Another thing would be to have the ability to add links for each sniff/error code, which could link to the official standard, like PSR2 could link to the individual paragraphs in the document on the FIG website.

[gsherwood]

The XML format is certainly one place to start.

My intention is to eventually bring up a PHPCS site with hand-written documentation for each error message, with code samples. I could copy/paste from the XML and then re-write anything a bit old or informal.

you mentioned that you write documentation professionally

I do write a lot documentation as part of my job, but I'm not a professional writer. Part of what I do is write from scratch. Another part is taking existing rough notes and turning it into a more complete document. That's really all I think is needed in this specific case. It's a bit of grunt work to start with, followed by a lot of polish.

I thought that the first thing I'd need to do is actually collect a list of all the error messages that PHPCS produces by going through the code of all the sniffs. For each, I wanted to gather:

• the error code
• the error message
• the severity (error or warning)
• the error message data (e.g., a class name, a method name, whatever helps customise messages)

And if I had time, I'd also produce a snippet of good and bad sample code for each one showing the condition that could cause the error message to be generated.

My next step would be to take a look at that data and try to figure out an easy-to-read format for displaying it all, before re-formatting and adding custom descriptions for each message.

So for me, it's not really about producing super clean and clear documentation right from the get go. My first step is just about gathering raw data. If I have that, I think it could be prettied up enough to put it into the wiki and at least have a list of available error messages. If that's generated from the XML files, that's great. If it's manually collected, I think that's fine too.

[Basje]

I thought that the first thing I'd need to do is actually collect a list of all the error messages that PHPCS produces by going through the code of all the sniffs. For each, I wanted to gather:

• the error code
• the error message
• the severity (error or warning)
• the error message data (e.g., a class name, a method name, whatever helps customise messages)

And if I had time, I'd also produce a snippet of good and bad sample code for each one showing the condition that could cause the error message to be generated.

Got a preferred location where we can collect this data?

[gsherwood]

Got a preferred location where we can collect this data?

I'll end up throwing it in the wiki, but I know you can't send PRs for Github wiki repos, which is a pain. So anywhere is fine. A gist might be a good option.

[GaryJones]

Manually compiled, but would the data in this format be useful?

<errormessages>
    <error>
        <code>Generic.Arrays.DisallowLongArraySyntax.Found</code>
        <message>Short array syntax must be used to define arrays</message>
        <severity>error</severity>
        <data></data>
        <fixable>1</fixable>
        <notes>Also seen as a non-fixable error for live coding/parse error</notes>
    </error>
    <error>
        <code>Generic.Arrays.DisallowShortArraySyntax.Found</code>
        <message>Short array syntax is not allowed</message>
        <severity>error</severity>
        <data></data>
        <fixable>1</fixable>
        <notes></notes>
    </error>
    <error>
        <code>Generic.Arrays.ArrayIndent.KeyIncorrect</code>
        <message>Array key not indented correctly; expected %s spaces but found %s</message>
        <severity>error</severity>
        <data>expectedIndent, foundIndent</data>
        <fixable>1</fixable>
        <notes></notes>
    </error>
    <error>
        <code>Generic.Arrays.ArrayIndent.CloseBraceNotNewLine</code>
        <message>Closing brace of array declaration must be on a new line</message>
        <severity>error</severity>
        <data></data>
        <fixable>1</fixable>
        <notes></notes>
    </error>
    <error>
        <code>Generic.Arrays.ArrayIndent.CloseBraceIncorrect</code>
        <message>Array close brace not indented correctly; expected %s spaces but found %s</message>
        <severity>error</severity>
        <data>expectedIndent, foundIndent</data>
        <fixable>1</fixable>
        <notes></notes>
    </error>

    <error>
        <code>Generic.Classes.OpeningBraceSameLine.MissingBrace</code>
        <message>Possible parse error: %s missing opening or closing brace</message>
        <severity>warning</severity>
        <data>Concatenated tokens content</data>
        <fixable>0</fixable>
        <notes></notes>
    </error>
    <error>
        <code>Generic.Classes.OpeningBraceSameLine.BraceOnNewLine</code>
        <message>Opening brace should be on the same line as the declaration for %s</message>
        <severity>error</severity>
        <data>Concatenated tokens content</data>
        <fixable>1</fixable>
        <notes></notes>
    </error>
    <error>
        <code>Generic.Classes.OpeningBraceSameLine.ContentAfterBrace</code>
        <message>Opening brace must be the last content on the line</message>
        <severity>error</severity>
        <data></data>
        <fixable>1</fixable>
        <notes></notes>
    </error>
    <error>
        <code>Generic.Classes.OpeningBraceSameLine.SpaceBeforeBrace</code>
        <message>Expected 1 space before opening brace; found %s</message>
        <severity>length</severity>
        <data></data>
        <fixable>1</fixable>
        <notes></notes>
    </error>
    <error>
        <code>Generic.Classes.DuplicateClassName.Found</code>
        <message>Duplicate %s name "%s" found; first defined in %s on line %s</message>
        <severity>warning</severity>
        <data>type, name, file, line</data>
        <fixable>0</fixable>
        <notes></notes>
    </error>

    <error>
        <code>Generic.PHP.ClosingPHPTag.NotFound</code>
        <message>The PHP open tag does not have a corresponding PHP close tag</message>
        <severity>error</severity>
        <data></data>
        <fixable>0</fixable>
        <notes></notes>
    </error>
    <error>
        <code>Generic.PHP.DiscouragedGoto.Found</code>
        <message>Use of the GOTO language construct is discouraged</message>
        <severity>warning</severity>
        <data></data>
        <fixable>0</fixable>
        <notes></notes>
    </error>
</errormessages>

[gsherwood]

Manually compiled, but would the data in this format be useful?

That format would certainly work.

I did notice some errors codes have type, name, file, line listed as data but I'm assuming that was a copy/paste thing instead of having special meaning. Unless it does have meaning?

[GaryJones]

I did notice some errors codes have type, name, file, line listed as data

Yeah, copy-pasta. Those pieces of data are correct for Generic.Classes.DuplicateClassName.Found, but shouldn't have been there for Generic.PHP.DiscouragedGoto.Found. Previous snippet updated.

There should obviously be one piece of data per placeholder in the message.