Is there a PHPCS standard targeting PHP docblocks?

Question

Is there a PHPCS coding standard that would check that proper annotations (@param, @return, @throws, etc.) are present in a docblock, including the proper spacing between them?

Answer 1

Try running the following command and see if it produces what you want:

phpcs /path/to/code --standard=Squiz --sniffs=Squiz.Commenting.FunctionComment,Squiz.Commenting.FunctionCommentThrowTag,Squiz.Commenting.ClassComment,Squiz.Commenting.FileComment,Squiz.Commenting.VariableComment

If it does, you could create your own standard that just includes those sniffs, and anything else you want to check. You do this by creating a ruleset.xml file and using that as your standard.

For example, you could create a file called mystandard.xml and include the following content:

<?xml version="1.0"?> <ruleset name="MyStandard">   <description>My custom coding standard.</description>   <rule ref="Squiz.Commenting.FunctionComment" />   <rule ref="Squiz.Commenting.FunctionCommentThrowTag" />   <rule ref="Squiz.Commenting.ClassComment" />   <rule ref="Squiz.Commenting.FileComment" />   <rule ref="Squiz.Commenting.VariableComment" /> </ruleset> 

Then you can run this command instead:

phpcs /path/to/code --standard=/path/to/mystandard.xml 

There are other things you can do in a ruleset.xml file. See the docs here: https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-Ruleset

Answer 2

In 2017 you have now more options:

• one of the best sniffs to check docblocks is TypeHintDeclarationSniff from SlevomatCodingStandard, works great with PHP 7, PHP 7.1, drop unused docs etc.
• also you can make use of another tool - PHP-CS-Fixer, there you can find more fixers, that will help you with docblock, just search "doc"