Skip to content

Commit b1a4bf8

Browse files
GaryJonesGaryJones
committed
Add Squiz and Generic Commenting with exclusions
There are still plenty of checks not made, but this first pass takes advantage of the existing code sniffs that match the WordPress handbook for inline documentation and commenting. See #241
1 parent 8e07f73 commit b1a4bf8

File tree

2 files changed

+103
-0
lines changed

2 files changed

+103
-0
lines changed

‎WordPress-Docs/ruleset.xml

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
<?xml version="1.0"?>
2+
<ruleset name="WordPress Docs">
3+
<description>WordPress Coding Standards for Inline Documentation and Comments</description>
4+
5+
<rule ref="Squiz.Commenting">
6+
<!-- Excluded to allow /* translators: ... */ comments -->
7+
<exclude name="Squiz.Commenting.BlockComment.SingleLine"/>
8+
<!-- Sniff seems to require indenting with spaces -->
9+
<exclude name="Squiz.Commenting.BlockComment.FirstLineIndent"/>
10+
<!-- Sniff seems to require indenting with spaces -->
11+
<exclude name="Squiz.Commenting.BlockComment.LineIndent"/>
12+
<!-- Sniff seems to require indenting with spaces -->
13+
<exclude name="Squiz.Commenting.BlockComment.LastLineIndent"/>
14+
<!-- WP requires /** for require() et al. See https://github.com/squizlabs/PHP_CodeSniffer/pull/581 -->
15+
<exclude name="Squiz.Commenting.BlockComment.WrongStart"/>
16+
<!-- WP handbook doesn't clarify one way or another, so ignore -->
17+
<exclude name="Squiz.Commenting.BlockComment.NoEmptyLineAfter"/>
18+
19+
<!-- WP prefers indicating @since, @package, @subpackage etc in class comments -->
20+
<exclude name="Squiz.Commenting.ClassComment.TagNotAllowed"/>
21+
22+
<!-- WP doesn't require //end ... for classes and functions -->
23+
<exclude name="Squiz.Commenting.ClosingDeclarationComment.Missing"/>
24+
25+
<!-- Excluded to allow param documentation for arrays -->
26+
<exclude name="Squiz.Commenting.DocCommentAlignment.SpaceAfterStar"/>
27+
28+
<!-- WP doesn't require a @author value for Squiz -->
29+
<exclude name="Squiz.Commenting.FileComment.IncorrectAuthor"/>
30+
<!-- WP doesn't require a @copyright value for Squiz -->
31+
<exclude name="Squiz.Commenting.FileComment.IncorrectCopyright"/>
32+
<!-- WP doesn't require @author tags -->
33+
<exclude name="Squiz.Commenting.FileComment.MissingAuthorTag"/>
34+
<!-- WP doesn't require @subpackage tags -->
35+
<exclude name="Squiz.Commenting.FileComment.MissingSubpackageTag"/>
36+
<!-- WP doesn't require @copyright tags -->
37+
<exclude name="Squiz.Commenting.FileComment.MissingCopyrightTag"/>
38+
<!-- WP has a different prefered order of tags -->
39+
<exclude name="Squiz.Commenting.FileComment.PackageTagOrder"/>
40+
<!-- WP has a different prefered order of tags -->
41+
<exclude name="Squiz.Commenting.FileComment.SubpackageTagOrder"/>
42+
<!-- WP has a different prefered order of tags -->
43+
<exclude name="Squiz.Commenting.FileComment.AuthorTagOrder"/>
44+
<!-- WP has a different prefered order of tags -->
45+
<exclude name="Squiz.Commenting.FileComment.CopyrightTagOrder"/>
46+
47+
<!-- WP prefers int and bool instead of integer and boolean -->
48+
<exclude name="Squiz.Commenting.FunctionComment.IncorrectParamVarName"/>
49+
<!-- WP prefers int and bool instead of integer and boolean -->
50+
<exclude name="Squiz.Commenting.FunctionComment.InvalidReturn"/>
51+
<!-- WP prefers indicating a @return null for early returns -->
52+
<exclude name="Squiz.Commenting.FunctionComment.InvalidReturnNotVoid"/>
53+
<!-- WP states not all functions require @return -->
54+
<exclude name="Squiz.Commenting.FunctionComment.MissingReturn"/>
55+
<!-- Excluded to allow param documentation for arrays -->
56+
<exclude name="Squiz.Commenting.FunctionComment.ParamCommentNotCapital"/>
57+
<!-- Excluded to allow param documentation for arrays -->
58+
<exclude name="Squiz.Commenting.FunctionComment.SpacingAfterParamName"/>
59+
<!-- WP doesn't require type hints -->
60+
<exclude name="Squiz.Commenting.FunctionComment.TypeHintMissing"/>
61+
62+
<!-- Exclude to allow duplicate hooks to be documented -->
63+
<exclude name="Squiz.Commenting.InlineComment.DocBlock"/>
64+
65+
<!-- Not in Inline Docs standard, and a code smell -->
66+
<exclude name="Squiz.Commenting.LongConditionClosingComment"/>
67+
68+
<!-- Not in Inline Docs standard, and needed to bypass WPCS checks -->
69+
<exclude name="Squiz.Commenting.PostStatementComment"/>
70+
71+
<!-- WP prefers int and bool instead of integer and boolean -->
72+
<exclude name="Squiz.Commenting.VariableComment.IncorrectVarType"/>
73+
<!-- WP demands a @since tag for class variables -->
74+
<exclude name="Squiz.Commenting.VariableComment.TagNotAllowed"/>
75+
<!-- WP prefers @since first -->
76+
<exclude name="Squiz.Commenting.VariableComment.VarOrder"/>
77+
</rule>
78+
79+
<rule ref="Generic.Commenting">
80+
<!-- WP has different alignment of tag values -->
81+
<exclude name="Generic.Commenting.DocComment.TagValueIndent"/>
82+
<!-- WP has a different prefered order of tags -->
83+
<exclude name="Generic.Commenting.DocComment.ParamNotFirst"/>
84+
<!-- Excluded to allow param documentation for arrays -->
85+
<exclude name="Generic.Commenting.DocComment.ParamGroup"/>
86+
<!-- WP prefers no empty line between @param tags and @return -->
87+
<exclude name="Generic.Commenting.DocComment.NonParamGroup"/>
88+
<!-- Excluded to allow param documentation for arrays -->
89+
<exclude name="Generic.Commenting.DocComment.TagsNotGrouped"/>
90+
<!-- Exclude to allow duplicate hooks to be documented -->
91+
<exclude name="Generic.Commenting.DocComment.ContentAfterOpen"/>
92+
<!-- Exclude to allow duplicate hooks to be documented -->
93+
<exclude name="Generic.Commenting.DocComment.SpacingBeforeShort"/>
94+
<!-- Exclude to allow duplicate hooks to be documented -->
95+
<exclude name="Generic.Commenting.DocComment.ContentBeforeClose"/>
96+
97+
<!-- WP allows @todo's in comments -->
98+
<exclude name="Generic.Commenting.Todo.CommentFound"/>
99+
<!-- WP allows @todo's in comments -->
100+
<exclude name="Generic.Commenting.Todo.TaskFound"/>
101+
</rule>
102+
</ruleset>

‎WordPress/ruleset.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
<description>WordPress Coding Standards</description>
44

55
<rule ref="WordPress-Core"/>
6+
<rule ref="WordPress-Docs"/>
67
<rule ref="WordPress-Extra"/>
78
<rule ref="WordPress-VIP"/>
89
</ruleset>

0 commit comments

Comments
 (0)