Limit when @var, @param and @return or their description is required

As a member of the Coding Standards Committee, I think the proposal can be considered accepted. It merely needs to be committed. And to be honest, I am holding off because I am concerned about the confusion it may cause.

I think there are some tests that still need to be adjusted.

From the coding_standards issue:

The comment may be omitted if the name of the variable matches the type, or the type with "Interface" appended.

How strictly are we interpreting "matches the type"? I think we should strip underscores and do a lowercase comparison, so we catch EntityTypeManagerInterface $entity_type_manager. From what I can tell from the MR we would only catch EntityTypeManagerInterface $entityTypeManager.

In cases where it is the snake_case formatting, the spirit of the new rule means we should be catching those as well, I agree. lowercasing + stripping out underscores sounds like a smart solution, +1.

Thanks!

1) Please fill out the issue title and description here, otherwise you make it very hard for Coder maintainers to understand which exact part of the linked issue you are trying to fix
2) Please fix the phpcs test fails
3) please add test cases with positive and negative examples so that we codify the expected behavior in tests

MR has been rebased and PHPCS fixed.

But the pipeline is now failing on the Drupal core regression tests.

I merged a quickfix to exclude that core file from testing.

Please merge from 9.x in your merge request. please add test cases with positive and negative examples so that we codify the expected behavior in tests

I've been doing the reading of the referenced issue 3376518, and it looks like commit #185 has a good/complete set of examples to base the new tests on.

@quietone, @klausi, anything to else to identify for tests?

@klausi Thank you for that quick fix for the core regression testing!

As I started to work on the addition of some tests, I determined that the comment can be skipped logic was not working as intended. Class/Interface upper camel case naming was being compared to the lower camel case naming of the variable.

To confirm scope of this issue, here are the tests for the sniffer

/**
 * Test class with properties.
 */
class Test {

  // PASS: DocBlock comment includes short description and @var tag with type
  /**
   * The entity type manager.
   *
   * @var \Drupal\Core\Entity\EntityTypeManagerInterface
   */
  protected EntityTypeManagerInterface $foobar;

  // PASS: DocBlock comment has @var tag with type and variable name is derived from type.
  /**
   * @var \Drupal\Core\Entity\EntityTypeManagerInterface
   */
  protected EntityTypeManagerInterface $entityTypeManagerInterface;

  // PASS: DocBlock comment has @var tag with type and variable name is derived from type.
  /**
   * @var \Drupal\Core\Entity\EntityTypeManagerInterface
   */
  protected EntityTypeManagerInterface $entityTypeManager;

  protected EntityTypeManagerInterface $entityType;

  // FAIL: DocBlock comment has @var tag with type and variable name is NOT derived from type.
  /**
   * @var \Drupal\Core\Entity\EntityTypeManagerInterface
   */
  protected EntityTypeManagerInterface $bar;

  // FAIL: Multiple type declarations require a DocBlock comment with a short description and @var tag with types
  /**
   * @var \Drupal\Core\Entity\EntityInterface|null
   */
  protected $entity;

}

Do we feel it is within the scope of this issue to create a `warning` for a type mismatch between the variable and @var tag?

  /**
   * @var \Drupal\Core\Session\AccountInterface
   */
  protected AccountProxyInterface $account;

A over arching question I have is whether these committing options are limited to variables that are typed when declared?

  // Variable is typed as it is being declared.
  protected AccountProxyInterface $account;

  // Variable is declared without typing.
  protected $account;

Do we feel it is within the scope of this issue to create a `warning` for a type mismatch between the variable and @var tag?

/**
* @var \Drupal\Core\Session\AccountInterface
*/
protected AccountProxyInterface $account;

Good question, I don't think so, that should get fixed in higher levels of phpstan coverage, so to me that doesn't have to be in scope for this issue.

A over arching question I have is whether these committing options are limited to variables that are typed when declared?

I would think this only works when the variable is typed as it is declared.