Problem/Motivation

The software does not report problems with comment tag ordering e.g. when a @throws tag occurs before a @return tag in the function comment block (see issue #2599524: Fixing order of documentation sections for /core/lib/Drupal for an example in D8 core).

Proposed resolution

The proposed resolution is to enhance DocCommentSniff.php to check the ordering of tags.

See also: Drupal API documentation standards for order of documentation sections

CommentFileSizeAuthor
#4 2605986-4-add-check-for-order.patch2.32 KBblackra
#2 2605986-2-add-check-for-order.patch1.79 KBblackra

Comments

blackra created an issue. See original summary.

blackra’s picture

blackra commented
Title: No check for ordering of comment tags » Missing check for ordering of comment tags
Issue summary: View changes
Status: Active » Needs review
StatusFileSize
new 2605986-2-add-check-for-order.patch1.79 KB

I have updated the issue summary and uploaded a patch. The patch has been manually tested against some of the files affected by issue #2599524: Fixing order of documentation sections for /core/lib/Drupal before and after the fix for that issue.

blackra’s picture

blackra commented
Status: Needs review » Needs work

I have found a problem with this patch. It does not pick up tags followed by punctuation.

Example:

@todo: Fix something

I don't know what doxygen does in these circumstances either, but the ordering is independent of whether this is a permitted construction.

blackra’s picture

blackra commented
Status: Needs work » Needs review
StatusFileSize
new 2605986-4-add-check-for-order.patch2.32 KB

Here is a patch that deals with @todo:

klausi’s picture

klausi
he/him||they/them
Primary language German
Location 🇦🇹 Vienna
commented
Status: Needs review » Needs work 
  1. +++ b/coder_sniffer/Drupal/Sniffs/Commenting/DocCommentSniff.php
@@ -451,7 +451,22 @@ class Drupal_Sniffs_Commenting_DocCommentSniff implements PHP_CodeSniffer_Sniff
+        // The tags for which the relative order is defined

    Inline comments should end with a dot. 

  2. +++ b/coder_sniffer/Drupal/Sniffs/Commenting/DocCommentSniff.php
@@ -451,7 +451,22 @@ class Drupal_Sniffs_Commenting_DocCommentSniff implements PHP_CodeSniffer_Sniff
+            '@see',
+            '@todo',
+            '@Plugin',

    not sure @Plugin should be in here, since that is an annotation, not a doc tag. I think we should remove that for now. 

  3. +++ b/coder_sniffer/Drupal/Sniffs/Commenting/DocCommentSniff.php
@@ -465,6 +480,32 @@ class Drupal_Sniffs_Commenting_DocCommentSniff implements PHP_CodeSniffer_Sniff
+            }
+            else {

    we use PHPCS coding standards for our sniffs to be more in line with PHPCS upstream code so the else should be on the same line as }. 

  4. +++ b/coder_sniffer/Drupal/Sniffs/Commenting/DocCommentSniff.php
@@ -465,6 +480,32 @@ class Drupal_Sniffs_Commenting_DocCommentSniff implements PHP_CodeSniffer_Sniff
+            if (array_key_exists($baseTagName, $orderedTags)) {

    why array_key_exists()? Can we use isset() instead? 

  5. +++ b/coder_sniffer/Drupal/Sniffs/Commenting/DocCommentSniff.php
@@ -465,6 +480,32 @@ class Drupal_Sniffs_Commenting_DocCommentSniff implements PHP_CodeSniffer_Sniff
+                }
+                else {

    else here again.

Then we need test cases. We need to check if we have covered this well enough in good.php. And we need additional checks in the DocCoomentUnitTest* files.

jonathan1055’s picture

jonathan1055 commented
Version: 8.x-2.x-dev » 8.x-3.x-dev
Related issues: +#2909391: Drupal.Commenting.VariableComment.VarOrder - @var before @code

This is useful and worth working on.

Also #2909391: Drupal.Commenting.VariableComment.VarOrder - @var before @code which could be closed as duplicate of this issue?