Add documentation for each sniff

[jrfnl]

All sniffs should be accompanied by documentation in the form of a SniffNameStandard.xml file. A SniffNameStandard.xml file contains a (short) description of each rule(s) the sniff checks and a code comparison for each check.

Examples can be found in the PHP_CodeSniffer repository:

• https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/Generic/Docs/Formatting/MultipleStatementAlignmentStandard.xml
• https://github.com/squizlabs/PHP_CodeSniffer/tree/master/src/Standards/Generic/Docs

The sniff documentation for the complete standard can be shown using the following command:

vendor/bin/phpcs --standard=WordPress --generator=Text

The sniff documentation for an individual sniff can be shown using the following command:

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

Aside from the text generator, there are also generators available for HTML and Markdown, which will allow us to use these documentation files to auto-generate documentation about the sniffs to be placed in, for instance, the wiki.

At this time, none of the WPCS native sniffs have this kind of documentation available.

This issue is intended to track progress for adding this documentation.

Adding this documentation is a focus-task for the WCEU contributor day 2019. During the WCEU Contributor day Gary (@GaryJones ) and Juliette (@jrfnl) will be available to help contributors get set up and answer any questions they may have.

Process

• When you start working on the documentation for one of these sniffs, please mention it in the WP Slack #core-coding-standards channel and mention your GitHub nickname (during the WCEU contributor day) or leave a comment in this issue (after WCEU Contributor day).
• Gary or Juliette will update this issue to show you have claimed that sniff.

Creating the documentation

Preparation

• Create a GitHub user account (if you haven't got one already).
• Fork this repository on GitHub.
• Make sure you have both git as well as Composer installed on your machine.
• Clone your fork to your local machine using your preferred git client.
• Run composer install from the command line in the root directory of your local clone of this repo.

For each sniff:

Note: where in the below text it says Category, replace this with the category (folder name) of the sniff. And where it says SniffName, replace it with the name of the sniff.

• Create a new branch off develop and name it docs/sniffname.

  git checkout -b "docs/sniffname" "develop"
  

• Create the XML file and place it in the correct WordPress/Docs/Category/ directory. You may need to create the directory if it doesn't yet exist.
• To verify what the sniff is checking for, look for addWarning() and/or addError() function calls in the sniff file in the WordPress/Sniffs/Category/ directory to see the error messages the sniff generates.
• To get inspiration for code examples, open the sniff's WordPress/Tests/Category/SniffNameUnitTest.inc file. Correct code will generally be marked with // OK., incorrect code will be marked with // Bad or // Error. 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 ./WordPress/Tests/Category/SniffNameUnitTest.inc --standard=WordPress --sniffs=WordPress.Category.SniffName
  

• Important: Guidelines for the documentation and the code samples:
  • Keep it as simple as possible.
  • Don't use code which can be traced back to a specific project.
  • Each line within the code sample should be max 48 characters.
  • The title of a "good" code sample should start with Valid: . The title of a "bad" code sample should start with Invalid: .
  • To highlight the "good" and the "bad" bits in the code examples, surround those bits with <em> ...</em> tags. These will be removed automatically when using the text generator, but ensure highlighting of the code in Markdown/HTML.
  • Also note: The indentation in the XML file should use spaces only. Four spaces for each indent. This applies not only to the code samples, but throughout the file.
  • And aside from the issue which the sniff is about, the rest of the code in each code sample should follow the WP Coding Standards.
• Once you've created the documentation, test it by running:

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

• If all is OK, commit your changes to the branch you created, push the branch upstream to your fork and create a pull request in this repo. Please mention this issue in your pull request description Related to #1722 so your pull request will show up in this issue.
• Gary and/or Juliette will review your PR and either approve and merge it or leave feedback on the pull request.
• Once a PR has been merged, this issue should be updated and the sniff action item moved to the "Finished" list and marked as complete.

To Do

• [ ] WordPress.DB.PreparedSQLPlaceholders
• [ ] WordPress.Security.EscapeOutput
• [ ] WordPress.Security.NonceVerification
• [ ] WordPress.Security.PluginMenuSlug
• [ ] WordPress.Security.ValidatedSanitizedInput
• [ ] WordPress.Utils.I18nTextDomainFixer
• [ ] WordPress.WP.GlobalVariablesOverride
• [ ] WordPress.WP.I18n

Claimed

• [ ] WordPress.Arrays.ArrayDeclarationSpacing - @rafaelfunchal - #2489
• [ ] WordPress.CodeAnalysis.AssignmentInTernaryCondition - @nic-sevic - #2488
• [ ] WordPress.DB.DirectDatabaseQuery - @jaymcp - #2458
• [ ] WordPress.DB.RestrictedClasses - @paulgibbs - #2455
• [ ] WordPress.DB.RestrictedFunctions - @paulgibbs - #2453
• [ ] WordPress.DB.SlowDBQuery - @petitphp - #2464
• [ ] WordPress.Files.FileName - @nic-sevic - #2492
• [ ] WordPress.PHP.DevelopmentFunctions - @gogdzl - #2490
• [ ] WordPress.PHP.DiscouragedPHPFunctions - @tikifez - #2494
• [ ] WordPress.PHP.NoSilencedErrors - @gogdzl - #2495
• [ ] WordPress.PHP.POSIXFunctions - @jaymcp - #2460
• [ ] WordPress.PHP.PregQuoteDelimiter - @tikifez - #2487
• [ ] WordPress.PHP.RestrictedPHPFunctions - @gogdzl - #2491
• [ ] WordPress.PHP.TypeCasts - @anukasha-mo
• [ ] WordPress.WP.AlternativeFunctions - @pamprn09 - #2496
• [ ] WordPress.WP.DiscouragedConstants - @rafaelfunchal - #2493
• [ ] WordPress.WP.DiscouragedFunctions - @nic-sevic

Finished

• [x] WordPress.Arrays.ArrayIndentation - @Mike-Hermans
• [x] WordPress.Arrays.ArrayKeySpacingRestrictions - @Mike-Hermans
• [x] WordPress.Arrays.CommaAfterArrayItem - @marconmartins (moved to PHPCSExtra since, see #2310)
• [x] WordPress.Arrays.MultipleStatementAlignment - @Mike-Hermans
• [x] WordPress.Classes.ClassInstantiation - @FORTE-WP (moved to PHPCSExtra since, see #2133)
• [x] WordPress.CodeAnalysis.EscapedNotTranslated - @jrfnl
• [x] WordPress.DateTime.CurrentTimeTimestamp - @jrfnl
• [x] WordPress.DateTime.RestrictedFunctions - @GaryJones
• [x] WordPress.DB.PreparedSQL - @jaymcp
• [x] WordPress.NamingConventions.PrefixAllGlobals - @ipstenu
• [x] WordPress.NamingConventions.ValidFunctionName - @richardkorthuis
• [x] WordPress.NamingConventions.ValidHookName - @jrfnl
• [x] WordPress.NamingConventions.ValidPostTypeSlug - @NielsdeBlaauw
• [x] WordPress.NamingConventions.ValidVariableName - @richardkorthuis - #2457
• [x] WordPress.PHP.DontExtract - @aiolachiara - #2456
• [x] WordPress.PHP.IniSet - @NielsdeBlaauw
• [x] WordPress.PHP.StrictInArray - @marconmartins
• [x] WordPress.PHP.YodaConditions - @ipstenu
• [x] WordPress.Security.SafeRedirect - @marconmartins / @NielsdeBlaauw
• [x] WordPress.WhiteSpace.CastStructureSpacing - @ckanitz
• [x] WordPress.WhiteSpace.ControlStructureSpacing - @ckanitz & @jrfnl
• [x] WordPress.WhiteSpace.DisallowInlineTabs - @ckanitz (moved to PHPCSExtra since, see #1912)
• [x] WordPress.WhiteSpace.ObjectOperatorSpacing - @jrfnl
• [x] WordPress.WhiteSpace.OperatorSpacing - @ckanitz
• [x] WordPress.WhiteSpace.PrecisionAlignment - @ckanitz (moved to PHPCSExtra since, see #2129)
• [x] WordPress.WP.Capabilities - @dingo-d
• [x] WordPress.WP.CapitalPDangit - @NielsdeBlaauw / @jrfnl
• [x] WordPress.WP.ClassNameCase - @jrfnl
• [x] WordPress.WP.CronInterval - @NielsdeBlaauw
• [x] WordPress.WP.DeprecatedClasses - @fkeijzer
• [x] WordPress.WP.DeprecatedFunctions - @fkeijzer
• [x] WordPress.WP.DeprecatedParameters - @fkeijzer
• [x] WordPress.WP.DeprecatedParameterValues - @fkeijzer
• [x] WordPress.WP.EnqueuedResources - @NielsdeBlaauw
• [x] WordPress.WP.EnqueuedResourceParameters - @NielsdeBlaauw
• [x] WordPress.WP.PostsPerPage - @GaryJones

Not needed

• ~~WordPress.CodeAnalysis.EmptyStatement~~ Replaced by PHPCS native sniff, see #1910

[jrfnl]

@Mike-Hermans, @marconmartins, @Ipstenu, @NielsdeBlaauw, @fkeijzer, @GaryJones, @ckanitz Just wanted to drop you all a note that I'm sorry that I haven't managed to review your PRs yet, even though I'm so incredibly happy with them all. Too many interesting conversations during this #WCEU kept me away from my computer. I promise that I will get to them all within the week once I'm back home in a few days.

[jrfnl]

@marconmartins, @Ipstenu, @NielsdeBlaauw, @GaryJones, @ckanitz I'm planning to release WPCS 2.2.0 in the very near future and I'd love to include as many of the docs as possible in that release.

Aside from the PRs @NielsdeBlaauw send in today, are there any open docs PRs which have been updated after review, but haven't had attention since ?

If so: my apologies. Please do leave a comment either here or on the PR itself to draw attention to it, so we can try to get the PR merged before the release.

Also - if a PR does still need an update, but you either don't have time to do so yourself or have lost interest, please leave a comment on the PR and we'll try and have someone else finish it off.

I really appreciate the work you've done on this and would love to have it go out in the world and help people when they are working with WPCS.

[janw-me]

After about 2 hours of I figured out. How to make an exception for snake_case:

	<rule ref="WordPress.NamingConventions.ValidVariableName">
		<properties>
			<property name="customPropertiesWhitelist[]" value="hive_ID"/>
		</properties>
	</rule>

Now the question is where should this be documented. I did found the xml docs. I don't think the format matches, I might be wrong. Is there a place where this should be documented? Can someone nudge me in the right direction?

[jrfnl]

@janw-me Sorry it took you so long. Next time, you may want to have a look at the wiki (where it is already documented): https://github.com/WordPress/WordPress-Coding-Standards/wiki/Customizable-sniff-properties#mixed-case-property-name-exceptions

Edit: Oh and please follow the format as per the example in the wiki. Your current format is not officially supported by PHPCS.

[janw-me]

With googling I didn't find it... And on the github pageI was looking for some "documentation" link but I should have looked for the wiki. I probably should call it a day....

And of course I'll follow the wiki format. the [] is fugly.

[jrfnl]

@janw-me Well, the readme also contains a link to the wiki and mentions customizing sniff behaviour: https://github.com/WordPress/WordPress-Coding-Standards#customizing-sniff-behaviour But if there are other ways in which you think this can be done which will help people find it more easily, I'd welcome a PR ;-)

[jrfnl]

@GaryJones @dingo-d

• I've just updated the sniff list in the description to be in line with the current sniffs in WPCS.
• I'd like to start running XML lint over the docs and preferably also check them against an XSD. PHPCS does not provide an XSD and as there is discussion on what form documentation should take in the future I'm not sure pulling an XSD for the docs there would be PR which would be merged. So, what about creating an XSD and adding it to PHPCSUtils ? If the upstream PHPCS PR would be accepted, we can defer to that, but in the mean time we'd have something against which the docs can be automatically validated for the most basic of QA via a check in the CI.

Opinions ? Anyone up for creating the XSD ?

[dingo-d]

I went and played around with PhpStorm's automatic schema definitions and I got this:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="documentation" type="documentationType"/>
  <xs:complexType name="codeType">
    <xs:simpleContent>
      <xs:extension base="xs:string">
        <xs:attribute type="xs:string" name="title" use="optional"/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>
  <xs:complexType name="code_comparisonType">
    <xs:sequence>
      <xs:element type="codeType" name="code" maxOccurs="unbounded" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="documentationType">
    <xs:sequence>
      <xs:element type="xs:string" name="standard"/>
      <xs:element type="code_comparisonType" name="code_comparison"/>
    </xs:sequence>
    <xs:attribute type="xs:string" name="title"/>
  </xs:complexType>
</xs:schema>

In one case (where I used ArrayIndentationStandard.xml as a basis for xsd generation) I got a difference in the <xs:complexType name="documentationType"> part:

<xs:complexType name="documentationType">
  <xs:choice maxOccurs="unbounded" minOccurs="0">
    <xs:element type="xs:string" name="standard"/>
    <xs:element type="code_comparisonType" name="code_comparison"/>
  </xs:choice>
  <xs:attribute type="xs:string" name="title"/>
</xs:complexType>

The xs:choice vs xs:sequence.

I'm not all too familiar with how xds needs to be structured. Do we need to just add that part inside the <xs:complexType name="documentationType"> tag?

[jrfnl]

@dingo-d Nice starting point, though it can probably be abstracted a little more. An XSD basically is a definition of what is elements and attributes are allowed within an XML document, how they can be nested and if they are expected in a certain order etc etc.

The W3Schools information is not bad to get a general impression of the definition language: https://www.w3schools.com/xml/schema_intro.asp Alternatively, for a deep dive, there are the official specs: https://www.w3.org/TR/xmlschema11-1/ ;-)

[jrfnl]

Oh and for inspiration, you could also have a look at the XSD for PHPCS rulesets: https://github.com/squizlabs/PHP_CodeSniffer/blob/master/phpcs.xsd