Amendment of Docblock Comment Standards

The Issue

Current coding standards for docblock comments are described on the Sample File (including Docblock Comment standards) page of the PEAR manual. The page in question contains a huge example file and the following phrase

Please take note of the vertical and horizontal spacing. They are part of the standard.

error    36   @category tag comment indented incorrectly. Expected 1 spaces but found 3.
error   221   Line indented incorrectly; expected at least 4 spaces, found 3
error   295   Expected 1 space after the longest type
error   296   Expected 1 space before variable type
.
.

See the results of PHP_CodeSniffer automated runs for more examples such as these. See the Examples section below for the code triggering such errors.

That part of the standards does not serve a useful purpose, since readability of the comments is not reduced by putting more spaces between phpdoc tag and its description. It is also extremely difficult to find more serious coding standards violations in a huge list of such errors.

Proposal

Whitespace issues

Replace the phrase

Please take note of the vertical and horizontal spacing. They are part of the standard.

by the following

The example below shows recommended vertical and horizontal spacing. When writing phpdoc tags additional spaces can be inserted between the tag name and description so that the descriptions line up in a block. Empty lines may be inserted between groups of phpdoc tags to promote readability.

PHP5 updates

The standards should also be updated to reflect changes in PHP5, since they are now mandating @access tags for all methods and requiring @static tags for static methods. These are obviously redundant in PHP5.

Other changes

@return tags are mandatory in the current standards, without exceptions. This essentially means having explicit '@return void' tags for methods that do not return anything (e.g. setFoo()) and having '@return ClassName' for constructors. @return tags should be optional for such methods, phpDocumentor will add 'void' and 'ClassName' as return values for them anyway.

@param tags are now required to contain the parameter name. This should be changed to make name optional (phpDocumentor handles this fine) but require @param tags to always have the same order as the method parameters.

Notes

It will make sense to extract the text of the standards from the example file, as it will greatly improve their readability and will allow URLs in them to be links.

Examples of code triggering errors

<?php

/**
 * Class representing a HTTP request
 *
 * ...
 *
 * @category   HTTP
 * @package    HTTP_Request2
 * @author     Alexey Borzov <avb@php.net>
 * @license    http://opensource.org/licenses/bsd-license.php New BSD License
 * @version    CVS: $Id: Request2.php,v 1.3 2008/11/12 16:14:41 avb Exp $
 * @link       http://pear.php.net/package/HTTP_Request2
 */
?>

<?php

   /**
    * Appends a cookie to "Cookie:" header
    *
    * @param    string  cookie name
    * @param    string  cookie value
    * @return   HTTP_Request2
    * @throws   HTTP_Request2_Exception
    */
    public function addCookie($name, $value)
    {
    }
?>

error  1      Line indented incorrectly; expected at least 4 spaces, found 3
error     4     Expected 1 space before variable type
error     4     Doc comment var "cookie" does not match actual variable name "$name" at position 1
error     4     Expected 1 space after the longest type
error     5     Last parameter comment requires a blank newline after it
error     5     Expected 1 space before variable type
error     5     Doc comment var "cookie" does not match actual variable name "$value" at position 2