[Project] Add XML documentation for each sniff #1285

jrfnl · 2021-04-13T16:50:59Z

Project description

Behind the scenes, a side-project has started to create a (GitHub Pages) website for this project with helpful information about the things PHPCompatibility detects and how to fix them.

@afilina has done amazing work creating a documentation generation engine which will create a page with the basic information about each sniff from the docblocks in the sniff code itself.

To enhance this basic information with details on how to fix issues, we are looking to introduce XML documentation files for each sniff.
The information contained in these XML files will be added to the GitHub Pages document for each sniff automatically via the engine created by Anna.

About the XML documentation

The choice for XML documentation files is rooted in the fact that PHPCS itself supports that format natively and can display the information on the command line.

To see an example of this in action, run the below command for the PHPCS native documentation about the sniffs in the PSR12 standard:

phpcs --standard=PSR12 --generator=Text

The sniff documentation for an individual sniff can be shown like so:

phpcs --standard=PSR12 --generator=Text --sniffs=PSR12.Keywords.ShortFormKeywords

Naming Conventions for the XML files

PHPCS has strict naming conventions for the XML files to allow the build-in documentation generators to work with them.

Type	Sniff file	Docs file
Convention:	`Standard/Sniffs/Category/SniffNameSniff.php`	`Standard/Docs/Category/SniffNameStandard.xml`
Example for PHPCompatibility:	`PHPCompatibility/Sniffs/Lists/NewShortListSniff.php`	`PHPCompatibility/Docs/Lists/NewShortListStandard.xml`

By complying with these naming conventions the sniff documentation will be usable, both from the PHPCS command-line using phpcs --standard=PHPCompatibility --generator=Text, as well as by the documentation generation engine which will generate the GitHub Pages site.

XML file format

Example taken from the PSR12 documentation in PHPCS itself:

<documentation title="Short Form Type Keywords">
    <standard>
    <![CDATA[
    Short form of type keywords MUST be used i.e. bool instead of boolean, int instead of integer etc.
    ]]>
    </standard>
    <code_comparison>
        <code title="Valid: Short form type used.">
        <![CDATA[
$foo = <em>(bool)</em> $isValid;
        ]]>
        </code>
        <code title="Invalid: Long form type type used.">
        <![CDATA[
$foo = <em>(boolean)</em> $isValid;
        ]]>
        </code>
    </code_comparison>
</documentation>

Things to take note of:

The title attribute in the <documentation> tag should generally reflect the name of the sniff.
Each XML file can contain multiple <standard> blocks.
Each <standard> block can be accompanied by one or more <code_comparison> blocks.
Each code comparison block should have two <code> sets, the first one showing "valid" code, i.e. code which is PHP cross-version compatible, the second one showing "invalid" code, i.e. code which would be flagged by the PHPCompatibility sniff.
The "valid" code sample description should - in most cases - be prefixed with "Cross version compatible:".
The "invalid" code sample description should - in most cases - be prefixed with a version indication, like "PHP < 7.0" or "PHP >= 7.4".
Please be aware that the < and > characters will need to be encoded for use in XML, i.e. > and <.
If possible, the specific code which triggers the flagging by PHPCompatibility should be surrounded by <em> tags to highlight it (for non-text generators).
The first line of the code samples should not be indented. If the code sample calls for it, subsequent lines can be (space) indented.
Each line within the code sample should be max 48 characters as otherwise the display on the command-line can be off.
All indentation in the XML file should be four-space based indentation. Do not use tabs.

Also note:

The documentation in this repo is expected to have the following XML header (with the "title" value replaced by the sniff name):

<?xml version="1.0"?>
<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
    title="Sniff Name"
    >

Code samples should generally be "anonymized".
I.e. don't use code which can be traced back to a specific project.
You can use blank lines in the <standard> and <code> blocks to improve readability of the information.
There is no character limit, so if a sniff warrants an extensive explanation on how to create cross-version compatible code, feel free to be verbose.

What about complex sniffs ?

As a rule of thumb, each individual error code should get its own "standard" description and/or code sample.

For "simple" sniffs, i.e. sniffs which only look for only one or a few related things, a single XML file should be introduced following the above naming conventions.

For "complex" sniffs which look for a lot of different issues, like for instance, the RemovedFunctions sniff, a base XML file should be created following the above guidelines, then, specifically for use and display on the website, additional XML files for individual error codes can be created in a subdirectory.

This would look like this:

- PHPCompatibility
  |- Docs
     |- Category
        |- SniffNameStandard.xml
        |- SniffName
           |- ErrorCode1.xml
           |- ErrorCode2.xml
           |- ErrorCode3.xml

Note: The additional "error code"-based XML files will not display on the command line. They will only be used for the website.

Action list

To do

Claimed/Work in Progress

PHPCompatibility.FunctionDeclarations.RemovedOptionalBeforeRequiredParam (@jrfnl) - PR FunctionDeclarations/RemovedOptionalBeforeRequiredParam: review + bug fix for nullable types #1692
PHPCompatibility.UseDeclarations.NewGroupUseDeclarations (@Flyingmana) - PR [xml doc] NewGroupUseDeclarations and NewGroupUseConstFunction #1470
PHPCompatibility.UseDeclarations.NewUseConstFunction (@Flyingmana) - PR [xml doc] NewGroupUseDeclarations and NewGroupUseConstFunction #1470

Done

No Action Needed

~~PHPCompatibility.Extensions.RemovedExtensions~~ (sniff will be removed)
~~PHPCompatibility.FunctionDeclarations.NewArrowFunction~~ (sniff will be removed)
~~PHPCompatibility.Keywords.ForbiddenNamesAsDeclared~~ (sniff removed)
~~PHPCompatibility.Keywords.ForbiddenNamesAsInvokedFunctions~~ (sniff removed)
PHPCompatibility.Upgrade.LowPHP (not a functional sniff)
PHPCompatibility.Upgrade.LowPHPCS (not a functional sniff)

Want to contribute ?

Leave a comment below to claim a sniff to start work on.

One of the admins of the repo will then move the sniff to the "Claimed" list and your GitHub handle will be added next to it.

How to contribute

Fork this repository
Clone your fork/this repository to your local machine & run composer install
Create a new branch off develop for your changes.
Create the XML file and place it in the correct PHPCompatibility/Docs/Category/ directory.
You may need to create the directory if it doesn't exist yet.
To verify what the sniff is checking for, look for addWarning(), addError() or addMessage() method calls in the sniff file in the PHPCompatibility/Sniffs/Category/ directory to see the error messages the sniff generates.
To get inspiration for code examples, open the sniff's PHPCompatibility/Tests/Category/SniffNameUnitTest.inc file.
If the sniff generates several error messages and you are unsure which error applies to which code, you can run the following command to get a better understanding of which code triggers which error/warning:
```
vendor/bin/phpcs -s ./PHPCompatibility/Tests/Category/SniffNameUnitTest.inc --standard=PHPCompatibility --report=full,source --sniffs=PHPCompatibility.Category.SniffName --runtime-set testVersion 4.0-
```
To find information about exactly what has changed and how to make the code cross-version compatible, use the links in the sniff class docblock to find the relevant information in the PHP RFCs and manual.

Once you have finished writing up the sniff documentation, be sure to test it on the command-line:

vendor/bin/phpcs --standard=PHPCompatibility --generator=Text --sniffs=PHPCompatibility.Category.SniffName

Do a final review of your documentation to make sure it follows all the guidelines in the above "XML file format" section.
Commit your changes, push the new branch up to your own fork and create a pull request to this repository.
Please mention this issue in your pull request description "Related to [Project] Add XML documentation for each sniff #1285" so your pull request will be linked to this issue.

The text was updated successfully, but these errors were encountered:

jrfnl added documentation good first issue labels Apr 13, 2021

This was referenced Apr 13, 2021

Release a new version #1284

Closed

[xml doc] RemovedPCREModifiers #1272

Closed

jrfnl mentioned this issue Mar 9, 2022

Classes/NewConstVisibility: add XML documentation #1323

Merged

jrfnl mentioned this issue May 30, 2022

Reference of sniff errors/warnings and their resolution #532

Open

jrfnl mentioned this issue Jan 12, 2023

Please do a new Release #1468

Closed

This was referenced Mar 27, 2023

[xml doc] RemovedPHP4StyleConstructors #1292

Merged

[xml doc] ReservedFunctionNames #1293

Merged

[xml doc] ArgumentFunctionsReportCurrentValue #1294

Merged

[xml doc] RemovedPCREModifiers #1295

Merged

jrfnl mentioned this issue May 14, 2023

Add checklist for XML docs reviews #1546

Merged

jrfnl mentioned this issue Jan 29, 2024

Make sniff documentation more useful and more discoverable PHPCSStandards/PHP_CodeSniffer#317

Open

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Project] Add XML documentation for each sniff #1285

[Project] Add XML documentation for each sniff #1285

jrfnl commented Apr 13, 2021 •

edited

[Project] Add XML documentation for each sniff #1285

[Project] Add XML documentation for each sniff #1285

Comments

jrfnl commented Apr 13, 2021 • edited

Project description

About the XML documentation

Naming Conventions for the XML files

XML file format

What about complex sniffs ?

Action list

To do

Claimed/Work in Progress

Done

No Action Needed

Want to contribute ?

How to contribute

jrfnl commented Apr 13, 2021 •

edited