Is there a PHPCS standard targeting PHP docblocks?

php phpdoc codesniffer
BenMorel picture BenMorel · Dec 7, 2012 · Viewed 8.5k times · Source

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

Greg Sherwood picture Greg Sherwood · Dec 8, 2012

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

Related questions

PHPDoc type hinting for array of objects?

So, in PHPDoc one can specify @var above the member variable declaration to hint at its type. Then an IDE, for ex. PHPEd, will know what type of object it's working with and will be able to provide a code …

Read More
PHP Function Comments

Just a quick question: I've seen that some PHP functions are commented at the top, using a format that is unknown to me: /** * * Convert an object to an array * * @param object $object The object to convert * @return array * */ My IDE …

Read More
Best way to document Array options in PHPDoc?

I'm struggling to write readable and easy to understand documentation that describes the multi-tree structure for Array options that are passed to a function. Here is an example array structure. $arr = [ 'fields' => [ 'title' => [ 'name' => 'Document.title', 'format' =&…

Read More