Bad test: Inline doc block comments are not allowed

So it looks like we just want to allow /** @var ... */ inline comments that are used for type inference for IDEs, all other inline comments should still use the "//" notation.

This should be fixed in 8.x-2.x first and can then be backported. And this should come with a test case in good.php.

I can't see anywhere where in line doc comments are disallowed by the Drupal coding standards.
But rather see descriptions of the standards that implies their necessity. Not just for declaring /** @var ... */ comments.

Referring to https://www.drupal.org/coding-standards/docs#drupal

/**
 * Sample summary line.
 *
 * Next paragraph. Etc.
 */
(code being documented goes here, such as a function declaration, class, etc.)

'(code being document, such as function declaration, class, etc..)'
Etc being the word that implies other code may be documented.

Referring to https://www.drupal.org/coding-standards/docs#inline

@todo statements in inline comments follow the same rules as using the @todo tag in docblocks. An example:

  // Some other comment here.
  // @todo Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
  //   nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
  //   sed diam voluptua.
  // We explicitly delete all comments.
  comment_delete($cid);

Given that "using the @todo tag in docblocks." links to https://www.drupal.org/coding-standards/docs#todo This suggests that if we are going to place a @todo in inline comments then, admittedly contrary to the given example, the @todo must be in an inline doc comment or it will be ignored.

Nowhere in this documentation are in line doc comments explicitly disallowed.

It makes much more sense that if something is not explicitly disallowed then it is in fact allowed.

The point is that doc blocks are used for blocks before functions, classes etc.

C style comments (/* */) and standard C++ comments (//) are both fine, though the former is discouraged within functions (even for multiple lines, repeat the // single-line comment).

from https://www.drupal.org/node/1354#inline

So in function bodies using // comments is preferred in Drupal. If you find any other usage besides /** @var ... let me know, otherwise I think we can close this since /** @var ... is an exception in the rules already.

And @todo comments work just fine after // ?

since /** @var ... is an exception in the rules already.

If @var is an exception, then why does the code-sniffer not allow it?

I'm currently having trouble seeing how my code can fulfil both this and normal PHP inspections. Children of EntityAccessControlHandler::checkAccess must accept an EntityInterface instead of my entity class (because PHP doesn't have generics). The @var comment is essential to be able to access my entity's methods at this point. The only way to do that and pass the code inspection is to turn off the code-sniffer, which rather defeats the point.

Coder allows /** @var just fine. Could you test with the most recent Coder release and post a code snippet that throws the error for you?

Please reopen if this is still an issue.

Using phpcs 2.8.1 and coder 8.12 I'm still getting this.

Triggered by contrib/drupal/core/lib/Drupal/Core/Datetime/Element/Datetime.php

  /**
   * {@inheritdoc}
   */
  public function getInfo() {
    $date_format = '';
    $time_format = '';
    // Date formats cannot be loaded during install or update.
    if (!defined('MAINTENANCE_MODE')) {
      if ($date_format_entity = DateFormat::load('html_date')) {
        /** @var $date_format_entity \Drupal\Core\Datetime\DateFormatInterface */
        $date_format = $date_format_entity->getPattern();
      }
      if ($time_format_entity = DateFormat::load('html_time')) {
        /** @var $time_format_entity \Drupal\Core\Datetime\DateFormatInterface */
        $time_format = $time_format_entity->getPattern();
      }
    }

With PHPCS 2.9.1 and Coder 8.2.12

This is allowed:

  /** @var string $var */

--

But this throws a warning:

  /**
   * @var string $var1
   * @var string $var2
   */

PHPStom autocompleted the multi-line format when type hinting the key and value variables for a foreach loop.

/** @var string $var */ isn't allowed in Coder 8.3 and PHPCS 3.4.0

I relaxed the Coder check now, so any inline comment that has @var in any form is allowed. That gives us flexibility until we decide @var formatting standards in inline comments.

Thank you very much for all your examples, I think they are all covered.