Doc Comment

Enforces rules related to the formatting of DocBlocks ("Doc Comments") in PHP code.

DocBlocks are a special type of comment that can provide information about a structural element. In the context of DocBlocks, the following are considered structural elements: class, interface, trait, enum, function, property, constant, variable declarations and require/include[_once] statements.

DocBlocks start with a `/**` marker and end on `*/`. This sniff will check the formatting of all DocBlocks, independently of whether or not they are attached to a structural element.
A DocBlock must not be empty.

Valid: DocBlock with some content.

/** * <em>Some content.</em> */

Invalid: Empty DocBlock.

/** * <em></em> */
The opening and closing DocBlock tags must be the only content on the line.

Valid: The opening and closing DocBlock tags have to be on a line by themselves.

<em>/**</em> * Short description. <em>*/</em>

Invalid: The opening and closing DocBlock tags are not on a line by themselves.

<em>/** Short description. */</em>
The DocBlock must have a short description, and it must be on the first line.

Valid: DocBlock with a short description on the first line.

/** * <em>Short description.</em> */

Invalid: DocBlock without a short description or short description not on the first line.

/** * <em></em>@return int */

/** <em> *</em> * Short description. */
Both the short description, as well as the long description, must start with a capital letter.

Valid: Both the short and long description start with a capital letter.

/** * <em>S</em>hort description. * * <em>L</em>ong description. */

Invalid: Neither short nor long description starts with a capital letter.

/** * <em>s</em>hort description. * * <em>l</em>ong description. */
There must be exactly one blank line separating the short description, the long description and tag groups.

Valid: One blank line separating the short description, the long description and tag groups.

/** * Short description. <em> *<em> * Long description. <em> *</em> * @param int $foo */

Invalid: More than one or no blank line separating the short description, the long description and tag groups.

/** * Short description. <em> * * </em> * Long description.<em> </em> * @param int $foo */
Parameter tags must be grouped together.

Valid: Parameter tags grouped together.

/** * Short description. * <em> * @param int $foo * @param string $bar</em> */

Invalid: Parameter tags not grouped together.

/** * Short description. * * @param int $foo <em> *</em> * @param string $bar */
Parameter tags must not be grouped together with other tags.

Valid: Parameter tags are not grouped together with other tags.

/** * Short description. * <em> * @param int $foo</em> * * @since 3.4.8 * @deprecated 6.0.0 */

Invalid: Parameter tags grouped together with other tags.

/** * Short description. * <em> * @param int $foo * @since 3.4.8 * @deprecated 6.0.0</em> */
Tag values for different tags in the same group must be aligned with each other.

Valid: Tag values for different tags in the same tag group are aligned with each other.

/** * Short description. * * @since<em> 0.5.0</em> * @deprecated<em> 1.0.0</em> */

Invalid: Tag values for different tags in the same tag group are not aligned with each other.

/** * Short description. * * @since<em> 0.5.0</em> * @deprecated<em> 1.0.0</em> */
Parameter tags must be defined before other tags in a DocBlock.

Valid: Parameter tags are defined first.

/** * Short description. * * <em>@param string $foo</em> * * @return void */

Invalid: Parameter tags are not defined first.

/** * Short description. * * @return void * * <em>@param string $bar</em> */
There must be no additional blank (comment) lines before the closing DocBlock tag.

Valid: No additional blank lines before the closing DocBlock tag.

/** * Short description.<em> </em> */

Invalid: Additional blank lines before the closing DocBlock tag.

/** * Short description. <em> *</em> */