Docs: add missing XML documentation for sniffs #148
Comments
@jrfnl, I can help with this issue. I will start with the Should we document the options that a given sniff supports? If so, how? For example, the |
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. |
|
Sounds good to me. Thanks for the additional details. |
|
@jrfnl, in the next few days, I can create PRs to add documentation to the (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). |
|
I could take the PSR12 ones 👍🏼 |
Moved to "Claimed" 👍🏻 |
|
@jrfnl I want to learn how to create a proper sniff doc, so I can take care of |
|
@przemekhernik 👍🏻 Moved to "Claimed" |
|
@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? 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? |
@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
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. |
|
@przemekhernik Just looked at the code and the tests for that sniff and it looks like you unfortunately selected a sniff which has a huge chunk of untested code..., so the tests vs code approach will not be sufficient in this case. 😞 |
|
I'd be happy to claim the remaining |
|
@jonmcp Thank you. Added them to the "Claimed" list (and removed the PropertyLabel one - you are 100% correct, that one shouldn't have been on the list) |
|
Unfortunately I don't think I'll have much free time to finish the rest of the PSR12 documentation :( If anybody wants to pick up what I've been working on that would be great. |
|
@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. |
Coincidentally, today I was discussing about how to document our standard properties and config options. It really would be nice to be able to add some "official" way to add the configurable properties to the Sniffs docs (and, in parallel, maybe, be also able to have a "main" documentation file for the standard itself, allowing custom config options (and maybe also properties, if they are standard-wide). The above is both a declaration and a question, heh, because I've not found any way to, officially, document them (other than manual docs). So I assume it doesn't exist (neither standard or sniff level). Ciao :-) |
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
Docsdirectory 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:
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
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.Classes.ClassDeclarationSquiz.Classes.ClassFileNameSquiz.Classes.ValidClassNameSquiz.Commenting.BlockCommentSquiz.Commenting.ClassCommentSquiz.Commenting.ClosingDeclarationCommentSquiz.Commenting.EmptyCatchCommentSquiz.Commenting.FileCommentSquiz.Commenting.FunctionCommentSquiz.Commenting.InlineCommentSquiz.Commenting.LongConditionClosingCommentSquiz.Commenting.PostStatementCommentSquiz.Commenting.VariableCommentSquiz.ControlStructures.ControlSignatureSquiz.ControlStructures.ElseIfDeclarationSquiz.ControlStructures.InlineIfDeclarationSquiz.ControlStructures.SwitchDeclarationSquiz.Files.FileExtensionSquiz.Formatting.OperatorBracketSquiz.Functions.FunctionDeclarationArgumentSpacingSquiz.Functions.FunctionDuplicateArgumentSquiz.Functions.FunctionDeclarationSquiz.Functions.GlobalFunctionSquiz.Functions.MultiLineFunctionDeclarationSquiz.NamingConventions.ValidFunctionNameSquiz.NamingConventions.ValidVariableNameSquiz.Objects.ObjectInstantiationSquiz.Operators.ComparisonOperatorUsageSquiz.Operators.IncrementDecrementUsageSquiz.Operators.ValidLogicalOperatorsSquiz.PHP.CommentedOutCodeSquiz.PHP.DisallowBooleanStatementSquiz.PHP.DisallowComparisonAssignmentSquiz.PHP.DisallowInlineIfSquiz.PHP.DisallowMultipleAssignmentsSquiz.PHP.DisallowSizeFunctionsInLoopsSquiz.PHP.DiscouragedFunctionsSquiz.PHP.EmbeddedPhpSquiz.PHP.EvalSquiz.PHP.GlobalKeywordSquiz.PHP.InnerFunctionsSquiz.PHP.LowercasePHPFunctionsSquiz.PHP.NonExecutableCodeSquiz.Scope.MemberVarScopeSquiz.Scope.MethodScopeSquiz.Strings.ConcatenationSpacingSquiz.Strings.DoubleQuoteUsageNote: 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.VersionControl.GitMergeConflict- @rodrigoprimoSquiz.WhiteSpace.ControlStructureSpacing- @jaymcpSquiz.WhiteSpace.FunctionOpeningBraceSpace- @jaymcpSquiz.WhiteSpace.FunctionSpacing- @jaymcp [Documentation] Squiz: Function Spacing #451Squiz.WhiteSpace.LogicalOperatorSpacing- @jaymcpSquiz.WhiteSpace.OperatorSpacing- @jaymcpDone
Generic.Arrays.ArrayIndent- @rodrigoprimo Generic/ArrayIndent: add XML documentation #432Generic.CodeAnalysis.EmptyPHPStatement- @rodrigoprimo Generic/EmptyPHPStatement: add XML documentation #166Generic.Commenting.DocComment- @rodrigoprimo Generic/DocComment: add XML documentation #247Generic.Formatting.SpaceBeforeCast- @rodrigoprimo Add documentation for the SpaceBeforeCast sniff #159Generic.PHP.RequireStrictTypes- @rodrigoprimo Generic/RequireStrictTypes: add XML documentation #236Generic.PHP.Syntax- @rodrigoprimo Generic/PHP/Syntax: add XML documentation #175Generic.WhiteSpace.IncrementDecrementSpacing- @rodrigoprimo Generic/IncrementDecrementSpacing: add XML documentation #287Generic.WhiteSpace.LanguageConstructSpacing- @rodrigoprimo Generic/LanguageConstructSpacing: add XML documentation #177PSR12.Classes.ClosingBrace- @dingo-d [Documentation] PSR12 - Closing Brace #170PSR12.Classes.OpeningBraceSpace- @dingo-d [Documentation] PSR12 - Opening Brace Space #171PSR12.ControlStructures.BooleanOperatorPlacement- @dingo-d [Documentation] PSR12 - Boolean Operator Placement #181PSR12.ControlStructures.ControlStructureSpacing- @dingo-d [Documentation] PSR12 - Control Structure Spacing #182PSR12.Files.ImportStatement- @dingo-d [Documentation] PSR12 - Import Statement #232PSR12.Files.OpenTag- @dingo-d [Documentation] PSR12 - Open Tag #233PSR12.Functions.ReturnTypeDeclaration- @dingo-d [Documentation] PSR12 - Return Type Declaration #237PSR12.Properties.ConstantVisibility- @dingo-d [Documentation] PSR12 - Constant Visiblity #238Squiz.PHP.Heredoc- @jrfnl Squiz/Heredoc: add XML doc #634Squiz.WhiteSpace.FunctionClosingBraceSpace- @przemekhernik [Documentation] Squiz.WhiteSpace.FunctionClosingBraceSpace #408Squiz.WhiteSpace.MemberVarSpacing- @jaymcp [Documentation] Squiz: Member Var Spacing #373Squiz.WhiteSpace.ScopeClosingBrace- @jaymcp [Documentation] Squiz: Scope Closing Brace #353Squiz.WhiteSpace.SuperfluousWhitespace- @jaymcp [Documentation] Squiz: Superfluous Whitespace #352Want 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.
The text was updated successfully, but these errors were encountered: