|» Metadata||» Status|
Amendment of Docblock Comment Standards
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.Literal application of that phrase in PHP_CodeSniffer, which is now the defacto standard for checking CS compliance, leads to it producing errors like
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.
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.
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.
@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.
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 errorsFile-level docblock
triggers the error "@foo tag comment indented incorrectly. Expected M spaces but found N." for all the tags in the docblock.Method-level docblock
triggers the following errors:
|» Dependencies||» Links|
|» Timeline||» Changelog|