It's allowed to have multiple code samples, todos or links in a document comment. Currently a false positive Drupal.Commenting.DocComment.TagsNotGrouped is thrown when multiple items are encountered.

CommentFileSizeAuthor
#1 2502837-1.patch1.56 KBpfrenssen
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

pfrenssen’s picture

FileSize
1.56 KB

Here's a test case that exposes the bug. What's also interesting is that this also hints at a second bug in the doc comment sniffer: it suggests to insert a blank line between the code snippet and the first @todo, but this blank line is already present.

Test case:

/**
 * @file
 * Some description here.
 *
 * A comprehensive guide with examples is available at:
 * @link http://example.com Test link @endlink.
 *
 * A second link:
 * @link http://example.com Test link @endlink.
 *
 * A first code sample:
 * @code
 * $variable = TRUE;
 * @endcode
 * A second code sample:
 * @code
 * $variable = FALSE;
 * @endcode
 *
 * A first todo:
 * @todo This code needs to be fixed.
 *
 * A second todo:
 * @todo This code also needs to be refactored.
 */

Test result:

1) Drupal_Sniffs_Commenting_DocCommentUnitTest::testSniff
[LINE 18] Expected 0 error(s) in DocCommentUnitTest.1.inc but found 1 error(s). The error(s) found were:
-> Tags must be grouped together in a doc comment (Drupal.Commenting.DocComment.TagsNotGrouped)
[LINE 20] Expected 0 error(s) in DocCommentUnitTest.1.inc but found 1 error(s). The error(s) found were:
-> Tags must be grouped together in a doc comment (Drupal.Commenting.DocComment.TagsNotGrouped)
[LINE 23] Expected 0 error(s) in DocCommentUnitTest.1.inc but found 1 error(s). The error(s) found were:
-> Separate the @endcode and @todo sections by a blank line. (Drupal.Commenting.DocComment.TagGroupSpacing)

tatarbj’s picture

Assigned: Unassigned » tatarbj
Liam Morland’s picture

Title: Multiple code snippets, todos and links are allowed in file doc blocks » Multiple code snippets, todos, and links are allowed in file doc blocks