Skip to content

Commit

Permalink
Add Squiz and Generic Commenting with exclusions
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@GaryJones
GaryJones committed May 8, 2015
1 parent 8e07f73 commit b1a4bf8
Show file tree
Hide file tree
Showing 2 changed files with 103 additions and 0 deletions.
102 changes: 102 additions & 0 deletions WordPress-Docs/ruleset.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
<?xml version="1.0"?>
<ruleset name="WordPress Docs">
<description>WordPress Coding Standards for Inline Documentation and Comments</description>

<rule ref="Squiz.Commenting">
<!-- Excluded to allow /* translators: ... */ comments -->
<exclude name="Squiz.Commenting.BlockComment.SingleLine"/>
<!-- Sniff seems to require indenting with spaces -->
<exclude name="Squiz.Commenting.BlockComment.FirstLineIndent"/>
<!-- Sniff seems to require indenting with spaces -->
<exclude name="Squiz.Commenting.BlockComment.LineIndent"/>
<!-- Sniff seems to require indenting with spaces -->
<exclude name="Squiz.Commenting.BlockComment.LastLineIndent"/>
<!-- WP requires /** for require() et al. See https://github.com/squizlabs/PHP_CodeSniffer/pull/581 -->
<exclude name="Squiz.Commenting.BlockComment.WrongStart"/>
<!-- WP handbook doesn't clarify one way or another, so ignore -->
<exclude name="Squiz.Commenting.BlockComment.NoEmptyLineAfter"/>

<!-- WP prefers indicating @since, @package, @subpackage etc in class comments -->
<exclude name="Squiz.Commenting.ClassComment.TagNotAllowed"/>

<!-- WP doesn't require //end ... for classes and functions -->
<exclude name="Squiz.Commenting.ClosingDeclarationComment.Missing"/>

<!-- Excluded to allow param documentation for arrays -->
<exclude name="Squiz.Commenting.DocCommentAlignment.SpaceAfterStar"/>

<!-- WP doesn't require a @author value for Squiz -->
<exclude name="Squiz.Commenting.FileComment.IncorrectAuthor"/>
<!-- WP doesn't require a @copyright value for Squiz -->
<exclude name="Squiz.Commenting.FileComment.IncorrectCopyright"/>
<!-- WP doesn't require @author tags -->
<exclude name="Squiz.Commenting.FileComment.MissingAuthorTag"/>
<!-- WP doesn't require @subpackage tags -->
<exclude name="Squiz.Commenting.FileComment.MissingSubpackageTag"/>
<!-- WP doesn't require @copyright tags -->
<exclude name="Squiz.Commenting.FileComment.MissingCopyrightTag"/>
<!-- WP has a different prefered order of tags -->
<exclude name="Squiz.Commenting.FileComment.PackageTagOrder"/>
<!-- WP has a different prefered order of tags -->
<exclude name="Squiz.Commenting.FileComment.SubpackageTagOrder"/>
<!-- WP has a different prefered order of tags -->
<exclude name="Squiz.Commenting.FileComment.AuthorTagOrder"/>
<!-- WP has a different prefered order of tags -->
<exclude name="Squiz.Commenting.FileComment.CopyrightTagOrder"/>

<!-- WP prefers int and bool instead of integer and boolean -->
<exclude name="Squiz.Commenting.FunctionComment.IncorrectParamVarName"/>
<!-- WP prefers int and bool instead of integer and boolean -->
<exclude name="Squiz.Commenting.FunctionComment.InvalidReturn"/>
<!-- WP prefers indicating a @return null for early returns -->
<exclude name="Squiz.Commenting.FunctionComment.InvalidReturnNotVoid"/>
<!-- WP states not all functions require @return -->
<exclude name="Squiz.Commenting.FunctionComment.MissingReturn"/>
<!-- Excluded to allow param documentation for arrays -->
<exclude name="Squiz.Commenting.FunctionComment.ParamCommentNotCapital"/>
<!-- Excluded to allow param documentation for arrays -->
<exclude name="Squiz.Commenting.FunctionComment.SpacingAfterParamName"/>
<!-- WP doesn't require type hints -->
<exclude name="Squiz.Commenting.FunctionComment.TypeHintMissing"/>

<!-- Exclude to allow duplicate hooks to be documented -->
<exclude name="Squiz.Commenting.InlineComment.DocBlock"/>

<!-- Not in Inline Docs standard, and a code smell -->
<exclude name="Squiz.Commenting.LongConditionClosingComment"/>

<!-- Not in Inline Docs standard, and needed to bypass WPCS checks -->
<exclude name="Squiz.Commenting.PostStatementComment"/>

<!-- WP prefers int and bool instead of integer and boolean -->
<exclude name="Squiz.Commenting.VariableComment.IncorrectVarType"/>
<!-- WP demands a @since tag for class variables -->
<exclude name="Squiz.Commenting.VariableComment.TagNotAllowed"/>
<!-- WP prefers @since first -->
<exclude name="Squiz.Commenting.VariableComment.VarOrder"/>
</rule>

<rule ref="Generic.Commenting">
<!-- WP has different alignment of tag values -->
<exclude name="Generic.Commenting.DocComment.TagValueIndent"/>
<!-- WP has a different prefered order of tags -->
<exclude name="Generic.Commenting.DocComment.ParamNotFirst"/>
<!-- Excluded to allow param documentation for arrays -->
<exclude name="Generic.Commenting.DocComment.ParamGroup"/>
<!-- WP prefers no empty line between @param tags and @return -->
<exclude name="Generic.Commenting.DocComment.NonParamGroup"/>
<!-- Excluded to allow param documentation for arrays -->
<exclude name="Generic.Commenting.DocComment.TagsNotGrouped"/>
<!-- Exclude to allow duplicate hooks to be documented -->
<exclude name="Generic.Commenting.DocComment.ContentAfterOpen"/>
<!-- Exclude to allow duplicate hooks to be documented -->
<exclude name="Generic.Commenting.DocComment.SpacingBeforeShort"/>
<!-- Exclude to allow duplicate hooks to be documented -->
<exclude name="Generic.Commenting.DocComment.ContentBeforeClose"/>

<!-- WP allows @todo's in comments -->
<exclude name="Generic.Commenting.Todo.CommentFound"/>
<!-- WP allows @todo's in comments -->
<exclude name="Generic.Commenting.Todo.TaskFound"/>
</rule>
</ruleset>
1 change: 1 addition & 0 deletions WordPress/ruleset.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
<description>WordPress Coding Standards</description>

<rule ref="WordPress-Core"/>
<rule ref="WordPress-Docs"/>
<rule ref="WordPress-Extra"/>
<rule ref="WordPress-VIP"/>
</ruleset>

0 comments on commit b1a4bf8

Please sign in to comment.