@file in a file containing a class triggers the "Namespaced classes, interfaces and traits should not begin with a file doc comment" error

[avpaderno]

Starting a class file with the following lines causes phpcs -s --standard="~/.config/phpcs_rulesets/Backdrop" ./ to report an error.

<?php
/**
 * @file
 * Contains \MyModule\ClassName.
 */

The error the following. (I changed the absolute filename to relative and shorted the separation lines.)

FILE: ./myclass_class.inc
-----------------
FOUND 1 ERROR AFFECTING 1 LINE
-----------------
 2 | ERROR | [x] Namespaced classes, interfaces and traits should not begin with a file doc comment
   |       |     (Backdrop.Commenting.FileComment.NamespaceNoFileDoc)
-----------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
-----------------

The Backdrop coding standards say @file should be used with file containing a class too.

/**
 * @file
 * Contains \Fully\Qualified\Namespace\And\NameOfTheClass.
 */

[indigoxela]

@kiamlaluno funny, if I paste your example into a file and check with phpcs, it passes here with the Backdrop ruleset.

What else is missing to trigger the error? Can you provide a full example, please?

And can you also run it with the -s param to show the exact sniff?

[avpaderno]

I edited the core/includes/anonymous.inc file to add the following lines, but I did not get any error from phpcs -s --standard="$HOME/.config/phpcs_rulesets/Backdrop" ./anonymous.inc. (I did not leave any empty line between the comment and <?php).

/**
 * @file
 * Contains \AnonymousUser.
 */

I was just creating a class file, and the editor I use, which automatically run phpcs --standard="$HOME/.config/phpcs_rulesets/Backdrop", reported that error.

This is the full content of the file causing that report.

<?php
/**
 * @file
 * Contains \MyModule\Iid.
*/

namespace MyModule;

/**
 * Handles a unique identifier associated to user accounts.
 */
class Iid implements IidInterface {

  /**
   * {@inheritoc}
   */
  public static function loadFromCookies() {

  }

  /**
   * {@inheritoc}
   */
  public static function loadFromDatabase($uid) {

  }

  /**
   * Constructs a \MyModule\Iid instance.
   */
  protected function __construct() {

  }
}

The report from phpcs -s --standard="$HOME/.config/phpcs_rulesets/Backdrop" ./iid.class.inc is the following.

FILE: ./iid.class.inc
-----------
FOUND 1 ERROR AFFECTING 1 LINE
-----------
 3 | ERROR | [x] Namespaced classes, interfaces and traits should not begin with a file doc comment
   |       |     (Backdrop.Commenting.FileComment.NamespaceNoFileDoc)
-----------

[avpaderno]

I tried changing namespace, removing the \ at the beginning of the namespace, but the report still shows that error.

[avpaderno]

I am not sure this is relevant, but I was first getting an error about a empty line that should not be put between <?php and the @file comment. Now, I do not get that error anymore, even when I add an empty line.

[avpaderno]

If I remove the namespace, I do not get the Namespaced classes, interfaces and traits should not begin with a file doc comment error anymore (which is expected), but I get a There must be no blank lines before the file comment error. If I re-add the namespace, I get the first error, but not the second.

[indigoxela]

So it actually seems to be related to the namespace declaration...

Again, can you please report the full output of phpcs -s ..., so we see the actual sniff causing the error?

Edit: all good, that just happened. 😸

[avpaderno]

There is another "issue," but I would leave that for another report: If the class name is namespaced, I can put an empty line before the @file comment; if the class name is not namespaced, I cannot put an empty line before the @file comment.

[indigoxela]

If I do it as follows, I get no errors:

<?php
/**
 * @file
 * Contains \MyModule\Iid.
 */

/**
 * Handles a unique identifier associated to user accounts.
 */
class Iid implements IidInterface {
}

In the code you posted, there's also an indent error, BTW - the closing */ of your file doc comment isn't indented.

So... sorry for the question, but ... namespace MyModule; - why do you add that namespace, anyway, what's the purpose?

[avpaderno]

I use the namespace to avoid conflicts with other modules.

[avpaderno]

The relevant code used by FileCommentSniff.php is the following one (line 61 and following).

        // Files containing exactly one class, interface or trait are allowed to
        // ommit a file doc block. If a namespace is used then the file comment must
        // be omitted.
        $oopKeyword = $phpcsFile->findNext([T_CLASS, T_INTERFACE, T_TRAIT], $stackPtr);
        if ($oopKeyword !== false) {
            $namespace = $phpcsFile->findNext(T_NAMESPACE, $stackPtr);
            // Check if the file contains multiple classes/interfaces/traits - then a
            // file doc block is allowed.
            $secondOopKeyword = $phpcsFile->findNext([T_CLASS, T_INTERFACE, T_TRAIT], ($oopKeyword + 1));
            // Namespaced classes, interfaces and traits should not have an @file doc
            // block.
            if (($tokens[$commentStart]['code'] === T_DOC_COMMENT_OPEN_TAG
                || $tokens[$commentStart]['code'] === T_COMMENT)
                && $secondOopKeyword === false
                && $namespace !== false
            ) {
                if ($tokens[$commentStart]['code'] === T_COMMENT) {
                    $phpcsFile->addError('Namespaced classes, interfaces and traits should not begin with a file doc comment', $commentStart, 'NamespaceNoFileDoc');
                }

The first comment makes sense to me, but it does not match with what the coding standards say.

[indigoxela]

Interesting... that rule has been forked from Drupal, so we might need to further adapt. However, as I read that part of our docs, the standard is still WIP. https://docs.backdropcms.org/doc-standards#classes

So not sure, if we now should adapt the sniff or wait for a core decision.

[avpaderno]

If I do it as follows, I get no errors:

<?php
/**
 * @file
 * Contains \MyModule\Iid.
 */

/**
 * Handles a unique identifier associated to user accounts.
 */
class Iid implements IidInterface {
}

That is because the class is not put in a namespace.

[indigoxela]

That is because the class is not put in a namespace.

I'm aware of that. 😁

Our phpcs sniffs are - just like our coding standards - WIP. The question here is: what has to happen next. Core (doc) discussion or sniff adaption?