Add documentation for each sniff

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/PHPCSStandards/PHP_CodeSniffer/blob/4.x/src/Standards/Generic/Docs/Formatting/MultipleStatementAlignmentStandard.xml
• https://github.com/PHPCSStandards/PHP_CodeSniffer/tree/4.x/src/Standards/Generic/Docs

And in the WPCS repository itself:

• https://github.com/WordPress/WordPress-Coding-Standards/blob/develop/WordPress/Docs/PHP/YodaConditionsStandard.xml: a simple example with a single check.
• https://github.com/WordPress/WordPress-Coding-Standards/blob/develop/WordPress/Docs/NamingConventions/ValidHookNameStandard.xml: an example with multiple <code_comparison> blocks for a sniff that checks more than one thing.
• https://github.com/WordPress/WordPress-Coding-Standards/blob/develop/WordPress/Docs/WP/CapabilitiesStandard.xml: an example with multiple <standard> blocks.
• https://github.com/WordPress/WordPress-Coding-Standards/tree/develop/WordPress/Docs: the full set of existing WPCS sniff documentation.

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.

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

Adding this documentation is an ongoing effort that has been a focus task at multiple WordCamp Contributor Days.

This effort started at the WCEU Contributor Day 2019, and several contributors have since helped move it forward across a number of Contributor Days throughout the years.

During Contributor Days, the WPCS maintainers 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 along with your GitHub nickname (during a Contributor Day) or leave a comment in this issue (outside of a Contributor Day).
• A WPCS maintainer 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 PHP (7.2 or higher), git, and Composer (2.x) 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.
  The easiest way to start is to copy an existing *Standard.xml file from WordPress/Docs/ and adjust it. This ensures the XML schema declaration on the <documentation> element is in place:

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

• The file name must follow the sniff's PHP class file name replacing Sniff.php suffix with Standard.xml. For example, the sniff in WordPress/Sniffs/PHP/YodaConditionsSniff.php must have its documentation in WordPress/Docs/PHP/YodaConditionsStandard.xml. Files that don't follow this naming convention will not be picked up by PHPCS.
• 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. This is the maximum width that fits in the side-by-side table rendered by the Text generator.
  • The title of a "good" code sample should start with Valid: .
    The title of a "bad" code sample should start with Invalid: .
  • The <standard> text should briefly explain why the rule exists, not just restate what the sniff name already says. A reader who has never heard of the rule should understand the motivation after one short paragraph.
  • To highlight the "good" and the "bad" bits in the code examples, surround those bits with <em>...</em> tags.
    Wrap only the part that actually differs between the valid and invalid examples, not the whole function call or the whole line. The reader should be able to spot the difference at a glance by comparing the two highlighted regions.
    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.
• A WPCS maintainer 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.Utils.I18nTextDomainFixer
• WordPress.WP.DiscouragedFunctions
• WordPress.WP.I18n

Up for grabs (previously claimed)

These sniffs were started by a previous contributor, but the work was not finished. Anyone is welcome to pick them up. To preserve credit for the original author, please branch from the original PR, add your commits on top, and open a new PR that links back to the original.

• WordPress.Security.EscapeOutput - @brentwilson-clariio - #2585
• WordPress.PHP.DiscouragedPHPFunctions - @tikifez - #2494 (outdated) / @jasonkenison #2584 (updated)

Claimed

• WordPress.PHP.TypeCasts - @brentwilson-clariio - #2591 (outdated) / @rodrigoprimo - #2738 (updated)
• WordPress.Security.NonceVerification - @dhanukanuwan
• WordPress.Security.ValidatedSanitizedInput - @rooh-wp311 - #2587 (outdated) / @rodrigoprimo - #2698 (updated)

Needs update after review

• WordPress.Files.FileName - @nic-sevic - #2492 (outdated) / @jasonkenison - #2590 (updated)
• WordPress.PHP.POSIXFunctions - @jaymcp - #2460

Finished

• WordPress.Arrays.ArrayDeclarationSpacing - @rafaelfunchal / @matt-galdino / @rodrigoprimo
• WordPress.Arrays.ArrayIndentation - @Mike-Hermans
• WordPress.Arrays.ArrayKeySpacingRestrictions - @Mike-Hermans
• WordPress.Arrays.CommaAfterArrayItem - @marconmartins (moved to PHPCSExtra since, see #2310)
• WordPress.Arrays.MultipleStatementAlignment - @Mike-Hermans
• WordPress.Classes.ClassInstantiation - @FORTE-WP (moved to PHPCSExtra since, see #2133)
• WordPress.CodeAnalysis.AssignmentInTernaryCondition - @nic-sevic / @rodrigoprimo
• WordPress.CodeAnalysis.EscapedNotTranslated - @jrfnl
• WordPress.DateTime.CurrentTimeTimestamp - @jrfnl
• WordPress.DB.DirectDatabaseQuery - @jaymcp / @rodrigoprimo
• WordPress.DB.RestrictedClasses - @paulgibbs / @rodrigoprimo
• WordPress.DB.SlowDBQuery - @petitphp / @rodrigoprimo
• WordPress.DateTime.RestrictedFunctions - @GaryJones
• WordPress.DB.PreparedSQL - @jaymcp
• WordPress.DB.RestrictedFunctions - @paulgibbs / @rodrigoprimo
• WordPress.NamingConventions.PrefixAllGlobals - @ipstenu
• WordPress.NamingConventions.ValidFunctionName - @richardkorthuis
• WordPress.NamingConventions.ValidHookName - @jrfnl
• WordPress.NamingConventions.ValidPostTypeSlug - @NielsdeBlaauw
• WordPress.NamingConventions.ValidVariableName - @richardkorthuis
• WordPress.PHP.DevelopmentFunctions - @gogdzl / @rodrigoprimo
• WordPress.PHP.DontExtract - @aiolachiara
• WordPress.PHP.IniSet - @NielsdeBlaauw
• WordPress.PHP.NoSilencedErrors - @gogdzl / @rodrigoprimo
• WordPress.PHP.PregQuoteDelimiter - @tikifez / @rodrigoprimo
• WordPress.PHP.RestrictedPHPFunctions - @gogdzl / @rodrigoprimo
• WordPress.PHP.StrictInArray - @marconmartins
• WordPress.PHP.YodaConditions - @ipstenu
• WordPress.Security.PluginMenuSlug - @jasonkenison
• WordPress.Security.SafeRedirect - @marconmartins / @NielsdeBlaauw
• WordPress.WhiteSpace.CastStructureSpacing - @ckanitz
• WordPress.WhiteSpace.ControlStructureSpacing - @ckanitz & @jrfnl
• WordPress.WhiteSpace.DisallowInlineTabs - @ckanitz (moved to PHPCSExtra since, see #1912)
• WordPress.WhiteSpace.ObjectOperatorSpacing - @jrfnl
• WordPress.WhiteSpace.OperatorSpacing - @ckanitz
• WordPress.WhiteSpace.PrecisionAlignment - @ckanitz (moved to PHPCSExtra since, see #2129)
• WordPress.WP.AlternativeFunctions - @pamprn09 / @bhubbard / @rodrigoprimo
• WordPress.WP.Capabilities - @dingo-d
• WordPress.WP.CapitalPDangit - @NielsdeBlaauw / @jrfnl
• WordPress.WP.ClassNameCase - @jrfnl
• WordPress.WP.CronInterval - @NielsdeBlaauw
• WordPress.WP.DeprecatedClasses - @fkeijzer
• WordPress.WP.DeprecatedFunctions - @fkeijzer
• WordPress.WP.DeprecatedParameters - @fkeijzer
• WordPress.WP.DeprecatedParameterValues - @fkeijzer
• WordPress.WP.DiscouragedConstants - @rafaelfunchal / @paulopmt1 / @rodrigoprimo
• WordPress.WP.EnqueuedResources - @NielsdeBlaauw
• WordPress.WP.EnqueuedResourceParameters - @NielsdeBlaauw
• WordPress.WP.GlobalVariablesOverride - @paulopmt1 / @rodrigoprimo
• WordPress.WP.PostsPerPage - @GaryJones

Not needed

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

Choose an uncompleted sniff from the To Do list, then inspect its WordPress/Sniffs/Category/SniffNameSniff.php file and matching WordPress/Tests/Category/SniffNameUnitTest.inc. Use the addWarning() or addError() messages and the test examples to create WordPress/Docs/Category/SniffNameStandard.xml. Run vendor/bin/phpcs --standard=WordPress --generator=Text --sniffs=WordPress.Category.SniffName and finish when the documentation renders correctly.