Drupal.Commenting.VariableComment.VarOrder was introduced in #2781933: Detect trailing semicolon in variable declarations and I'm missing its background. Is @var required to be first even before any @code tags?

  /**
   * Array of fields to update to an expression in case of a duplicate record.
   *
   * This variable is a nested array in the following format:
   * @code
   * <some field> => array(
   *  'condition' => <condition to execute, as a string>,
   *  'arguments' => <array of arguments for condition, or NULL for none>,
   * );
   * @endcode
   *
   * @var array
   */

The Drupal coding standards page api-documentation-and-comment-standards#order does not mention @code in the order of sections. Should it be considered a section?

Also we have:

    * @link http://github.com/zendframework/zf2 for the canonical source repository
    * @copyright Copyright (c) 2005-2013 Zend Technologies USA Inc. (http://www.zend.com)
    * @license http://framework.zend.com/license/new-bsd New BSD License
    *
    * A map of characters to be replaced through strtr.
    *
   * @var array

which fails the tests. @copyright and @license are not part of coding standards. @link is mentioned in our CS, but should not be considered a section from my pov.

Comments

mfernea created an issue. See original summary.

mfernea’s picture

mfernea commented
Issue summary: View changes
zaporylie’s picture

zaporylie
he/him
Primary language Polish
commented
Category: Support request » Bug report

According to https://www.drupal.org/docs/develop/coding-standards/api-documentation-a... order for @var and @todo is clear (@var prior to @todo) but either @code, @license, etc should be excluded from order check (blacklisted?) or entire second paragraph if it does not start with @.

mfernea’s picture

mfernea commented
Title: Drupal.Commenting.VariableComment.VarOrder - @var before @todo and @code » Drupal.Commenting.VariableComment.VarOrder - @var before @code
Issue summary: View changes

I updated the examples and added links to CS page.

jonathan1055’s picture

jonathan1055 commented
Version: 8.x-2.x-dev » 8.x-3.x-dev
Issue summary: View changes

Moving to the 8.x-3.x branch.
Core issue #2909371: Fix 'Drupal.Commenting.VariableComment.VarOrder' coding standard is postponed on this.

quietone’s picture

quietone commented
Status: Active » Needs review

I worked on the core issue #2909371: Fix 'Drupal.Commenting.VariableComment.VarOrder' coding standard today and reporting back here.

The Drupal coding standards page api-documentation-and-comment-standards#order does not mention @code in the order of sections. Should it be considered a section?

Can make an in issue in the Coding Standards project so that can be discussed.

Core does not have any '@copyright' or '@license' in doc blocks. So, that point seems to be outdated.

And '@link .. @endlink' is reported as an error. But I think this is correct for the Variable comment block where the explanation is after @var.

Also, there were no instances in Drupal core where an '@link .. @endlink' was moved as a result of enabling the sniff.

So, for me I would go with won't fix on this.

klausi’s picture

klausi
he/him||they/them
Primary language German
Location 🇦🇹 Vienna
commented
Status: Needs review » Closed (won't fix)

I agree - and I don't think we will need @var comments in the future as now you must always specify the type of your class property as type hint (at least for new code). Eventually we can remove the @var coding standard and enforce property type hints with a sniff from Slevomat.