Docs: add missing XML documentation for sniffs

[jrfnl]

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 [Documentation] PSR12 - Declare Statement #187)
  Note: this one is blocked until the sniff rewrite has been finished & merged.

To Do

• Generic.VersionControl.GitMergeConflict
• PSR12.Classes.AnonClassDeclaration (There is a first draft available created by @dingo-d, which can be iterated on [Documentation] PSR12 - Anonymous Class Declaration #167)
• PSR12.Files.FileHeader (There is a first draft available created by @dingo-d, which can be iterated on [Documentation] PSR12 - File Header #231)
• PSR12.Traits.UseDeclaration (There is a first draft available created by @dingo-d, which can be iterated on [Documentation] PSR12 - Use Declaration #239)
• 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.FunctionDuplicateArgument
• 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.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

• Squiz.Classes.ClassDeclaration - @braindawg [Docs] Add XML doc for Squiz.Classes.ClassDeclaration sniff #844
• Squiz.WhiteSpace.ControlStructureSpacing - @jaymcp
• Squiz.WhiteSpace.FunctionSpacing - @jaymcp [Documentation] Squiz: Function Spacing #451
• Squiz.WhiteSpace.LogicalOperatorSpacing - @jaymcp
• Squiz.WhiteSpace.OperatorSpacing - @jaymcp

Done

• Generic.Arrays.ArrayIndent - @rodrigoprimo Generic/ArrayIndent: add XML documentation #432
• Generic.CodeAnalysis.EmptyPHPStatement - @rodrigoprimo Generic/EmptyPHPStatement: add XML documentation #166
• Generic.Commenting.DocComment - @rodrigoprimo Generic/DocComment: add XML documentation #247
• Generic.Formatting.SpaceBeforeCast - @rodrigoprimo Add documentation for the SpaceBeforeCast sniff #159
• Generic.PHP.RequireStrictTypes - @rodrigoprimo Generic/RequireStrictTypes: add XML documentation #236
• Generic.PHP.Syntax - @rodrigoprimo Generic/PHP/Syntax: add XML documentation #175
• Generic.WhiteSpace.IncrementDecrementSpacing - @rodrigoprimo Generic/IncrementDecrementSpacing: add XML documentation #287
• Generic.WhiteSpace.LanguageConstructSpacing - @rodrigoprimo Generic/LanguageConstructSpacing: add XML documentation #177
• PSR12.Classes.ClosingBrace - @dingo-d [Documentation] PSR12 - Closing Brace #170
• PSR12.Classes.OpeningBraceSpace - @dingo-d [Documentation] PSR12 - Opening Brace Space #171
• PSR12.ControlStructures.BooleanOperatorPlacement - @dingo-d [Documentation] PSR12 - Boolean Operator Placement #181
• PSR12.ControlStructures.ControlStructureSpacing - @dingo-d [Documentation] PSR12 - Control Structure Spacing #182
• PSR12.Files.ImportStatement - @dingo-d [Documentation] PSR12 - Import Statement #232
• PSR12.Files.OpenTag - @dingo-d [Documentation] PSR12 - Open Tag #233
• PSR12.Functions.ReturnTypeDeclaration - @dingo-d [Documentation] PSR12 - Return Type Declaration #237
• PSR12.Properties.ConstantVisibility - @dingo-d [Documentation] PSR12 - Constant Visiblity #238
• Squiz.Commenting.BlockComment - @costdev [Docs] Add XML doc for Squiz.Commenting.BlockComment sniff #848
• Squiz.Classes.ClassFileName - @braindawg [Docs] Add XML doc for Squiz.Classes.ClassFileName sniff #843
• Squiz.Classes.ValidClassName - @braindawg [Docs] Add XML doc for Squiz.Classes.ValidClassName sniff #842
• Squiz.PHP.Heredoc - @jrfnl Squiz/Heredoc: add XML doc #634
• Squiz.WhiteSpace.FunctionClosingBraceSpace - @przemekhernik [Documentation] Squiz.WhiteSpace.FunctionClosingBraceSpace #408
• Squiz.WhiteSpace.MemberVarSpacing - @jaymcp [Documentation] Squiz: Member Var Spacing #373
• Squiz.WhiteSpace.ScopeClosingBrace - @jaymcp [Documentation] Squiz: Scope Closing Brace #353
• Squiz.WhiteSpace.SuperfluousWhitespace - @jaymcp [Documentation] Squiz: Superfluous Whitespace #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.

[rodrigoprimo]

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.

[jrfnl]

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.

Based on precedent in this repo, the documentation should outline the default behaviour of the sniff.

In docs for some external sniffs, I've sometimes mentioned that the behaviour is adjustable via properties, but I don't think that is done anywhere in this repo, so for now, I would leave it out. The wiki contains a page with details on all customisable properties anyhow.

This can be revisited at a later point in time, but for now, getting the initial version of the docs in is more important.

[rodrigoprimo]

Sounds good to me. Thanks for the additional details.

[rodrigoprimo]

@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)

[jrfnl]

@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).

[dingo-d]

I could take the PSR12 ones 👍🏼

[jrfnl]

I could take the PSR12 ones 👍🏼

Moved to "Claimed" 👍🏻