PHP_CodeSniffer: Docs: add missing XML documentation for sniffs

Sniffs in PHP_CodeSniffer should preferably be accompanied by documentation. There are currently still a number of sniffs which don’t have documentation.

Sniff documentation is provided via XML files in the standard’s Docs directory and is available to end-users via the command-line and/or can be compiled into an HTML or Markdown file.

To see an example of some of some available documentation, run:

phpcs --standard=PSR12 --generator=Text

Getting started

The CONTRIBUTING doc contains information on writing sniff documentation and guidelines which should be followed.

Action list

Blocked

PSR12.Files.DeclareStatement (There is a first draft available created by @dingo-d, which can be iterated on #187) Note: this one is blocked until the sniff rewrite has been finished & merged.

To Do

PSR12.Classes.AnonClassDeclaration (There is a first draft available created by @dingo-d, which can be iterated on #167)
PSR12.Files.FileHeader (There is a first draft available created by @dingo-d, which can be iterated on #231)
PSR12.Traits.UseDeclaration (There is a first draft available created by @dingo-d, which can be iterated on #239)
Squiz.Classes.ClassDeclaration
Squiz.Classes.ClassFileName
Squiz.Classes.ValidClassName
Squiz.Commenting.BlockComment
Squiz.Commenting.ClassComment
Squiz.Commenting.ClosingDeclarationComment
Squiz.Commenting.EmptyCatchComment
Squiz.Commenting.FileComment
Squiz.Commenting.FunctionComment
Squiz.Commenting.InlineComment
Squiz.Commenting.LongConditionClosingComment
Squiz.Commenting.PostStatementComment
Squiz.Commenting.VariableComment
Squiz.ControlStructures.ControlSignature
Squiz.ControlStructures.ElseIfDeclaration
Squiz.ControlStructures.InlineIfDeclaration
Squiz.ControlStructures.SwitchDeclaration
Squiz.Files.FileExtension
Squiz.Formatting.OperatorBracket
Squiz.Functions.FunctionDeclarationArgumentSpacing
Squiz.Functions.FunctionDeclaration
Squiz.Functions.GlobalFunction
Squiz.Functions.MultiLineFunctionDeclaration
Squiz.NamingConventions.ValidFunctionName
Squiz.NamingConventions.ValidVariableName
Squiz.Objects.ObjectInstantiation
Squiz.Operators.ComparisonOperatorUsage
Squiz.Operators.IncrementDecrementUsage
Squiz.Operators.ValidLogicalOperators
Squiz.PHP.CommentedOutCode
Squiz.PHP.DisallowBooleanStatement
Squiz.PHP.DisallowComparisonAssignment
Squiz.PHP.DisallowInlineIf
Squiz.PHP.DisallowMultipleAssignments
Squiz.PHP.DisallowSizeFunctionsInLoops
Squiz.PHP.DiscouragedFunctions
Squiz.PHP.EmbeddedPhp
Squiz.PHP.Eval
Squiz.PHP.GlobalKeyword
Squiz.PHP.Heredoc
Squiz.PHP.InnerFunctions
Squiz.PHP.LowercasePHPFunctions
Squiz.PHP.NonExecutableCode
Squiz.Scope.MemberVarScope
Squiz.Scope.MethodScope
Squiz.Strings.ConcatenationSpacing
Squiz.Strings.DoubleQuoteUsage

Note: a number of sniffs will be removed in v 4.0. Those have been deliberately excluded from the above action list.

Claimed/Work in Progress

Generic.Arrays.ArrayIndent - @rodrigoprimo
Generic.Commenting.DocComment - @rodrigoprimo #247
Generic.VersionControl.GitMergeConflict - @rodrigoprimo
Squiz.WhiteSpace.ControlStructureSpacing - @jonmcp
Squiz.WhiteSpace.FunctionClosingBraceSpace - @jonmcp
Squiz.WhiteSpace.FunctionOpeningBraceSpace - @przemekhernik
Squiz.WhiteSpace.FunctionSpacing - @jonmcp
Squiz.WhiteSpace.LogicalOperatorSpacing - @jonmcp
Squiz.WhiteSpace.OperatorSpacing - @jonmcp

Done

Generic.CodeAnalysis.EmptyPHPStatement - @rodrigoprimo #166
Generic.Formatting.SpaceBeforeCast - @rodrigoprimo #159
Generic.PHP.RequireStrictTypes - @rodrigoprimo #236
Generic.PHP.Syntax - @rodrigoprimo #175
Generic.WhiteSpace.IncrementDecrementSpacing - @rodrigoprimo #287
Generic.WhiteSpace.LanguageConstructSpacing - @rodrigoprimo #177
PSR12.Classes.ClosingBrace - @dingo-d #170
PSR12.Classes.OpeningBraceSpace - @dingo-d #171
PSR12.ControlStructures.BooleanOperatorPlacement - @dingo-d #181
PSR12.ControlStructures.ControlStructureSpacing - @dingo-d #182
PSR12.Files.ImportStatement - @dingo-d #232
PSR12.Files.OpenTag - @dingo-d #233
PSR12.Functions.ReturnTypeDeclaration - @dingo-d #237
PSR12.Properties.ConstantVisibility - @dingo-d #238
Squiz.WhiteSpace.MemberVarSpacing - @jonmcp #373
Squiz.WhiteSpace.ScopeClosingBrace - @jonmcp #353
Squiz.WhiteSpace.SuperfluousWhitespace - @jonmcp #352

Want to contribute ?

Leave a comment below to claim a sniff you’ll be working on.

PRs related to this task should preferably only contain the docs for one sniff each.

About this issue

Original URL
State: open
Created 7 months ago
Comments: 18 (16 by maintainers)

Most upvoted comments

@stronk7 You may be interested in having a read through #317…

jrfnl on Mar 19, 2024

@dingo-d Thank you for the heads-up and thank you for the work already done on this. Docs for 8 out of 12 sniffs were merged so far, so that’s great progress already!

I will move the remaining four back to “Unclaimed” and will close the PRs. If/when someone claims them and wants to continue on the work you’ve done for these already, the PR(s) can be reopened.

jrfnl on Mar 11, 2024

@jrfnl I have a small question about docs. Generally, I’m trying to use reverse engineering to check what specific sniff does to write docs based on the sniff code. Sometimes I’m wondering if there some better way. What is your/recommended approach here?

@przemekhernik Well, best is obviously if the docs would (have been) written when the sniff was, but for this exercise, reverse engineering is unfortunately needed.

I can imagine different people having different approaches, but I would normally run the sniff over the test case file using the code report to see what is being flagged with which error code and combine that with reading the test case file taking note of what is not being flagged too + reading the sniff code.

For this particular sniff, the command I’d use for the test case file would be like so:

phpcs -ps ./src/Standards/Squiz/Tests/WhiteSpace/FunctionClosingBraceSpaceUnitTest.inc --standard=Squiz --report=code,source --sniffs=Squiz.WhiteSpace.FunctionClosingBraceSpace

For example, I’m not sure how to check this part of the sniff. Also, I’ve get through opened issues and find out that there’s a issue for removing JS/CSS tokenizers. This one seems to be JS-one so should I bother myself about this in the docs?

Feel free to ignore anything JS/CSS specific while writing the docs as, as you already saw, support for JS/CSS will be dropped soon enough, so just focusing on what the sniff does for PHP code should be fine.

jrfnl on Feb 5, 2024

@jrfnl I want to learn how to create a proper sniff doc, so I can take care of Squiz.WhiteSpace.FunctionClosingBraceSpace as a first.

przemekhernik on Feb 1, 2024

I could take the PSR12 ones 👍🏼

Moved to “Claimed” 👍🏻

jrfnl on Dec 15, 2023

I could take the PSR12 ones 👍🏼

dingo-d on Dec 15, 2023

@jrfnl, in the next few days, I can create PRs to add documentation to the Generic sniffs that are missing docs.

(please let me know if you prefer that I claim one sniff at a time instead of claiming a group of sniffs as I’m doing here)

Great! Moved those to “claimed” now. Just make sure you submit each doc as a separate PR (but you knew that already).

jrfnl on Dec 14, 2023

Leave a comment below to claim a sniff you’ll be working on.

@jrfnl, I can help with this issue. I will start with the Generic.Formatting.SpaceBeforeCast sniff and, if all goes well, I can create PRs for more sniffs. I will make sure to create one PR per sniff.

Should we document the options that a given sniff supports? If so, how? For example, the Generic.Arrays.ArrayIndent supports indent, but I’m not sure how to document it by checking the instructions in CONTRIBUTING.md, and I was also not able to find any examples checking a few of the sniffs that are already documented.

rodrigoprimo on Dec 12, 2023