[policy] Set a standard for @var inline variable type declarations

Problem/Motivation

Core and contrib have been using inline variable type declarations in the wild. In the past there were several competing standards, but in recent months and years this has settled on one single standard which has gained widespread adoption (ref. original issue summary, and the discussion in the comments up to #40).

We need to document this standard.

Proposed resolution

Add documentation to the API documentation and comments coding standards page, in a new section titled "Drupal standard for inline variable type declarations", to be placed underneath the existing section Drupal standards for in-line code comments.

The @var tag can document variables in addition to class properties. This can be used when you know more about the type of a variable than is self-evident from the code, such as when you load a specific entity type, or a specific service. In this case you can typehint inline, which improves Developer Experience and Tools Experience.

Syntax example:

/** @var \Drupal\node\NodeInterface $node */
$node = $this->entityTypeManager->getStorage('node')->load(123);

When documenting variables with the @var tag note that you should use the special /** */ delimiters with a double opening asterisk. Always use the fully qualified namespace of the class or interface, and include the name of the variable at the end.

Remaining tasks

• Agree on the proposed standard to adopt, if possible
• Add documentation to the API documentation and comments coding standards page.
• Review the documentation addition to the API documentation and comments coding standards page.
• Make a patch for code that isn't using the adopted standard (on related issue #2305641: Use the "standard" format for @var inline variable type declarations).
• Add this standard to Coder.

User interface changes

None.

API changes

None, but new coding standards will be adopted.

Original report by @pfrenssen

There are two three standards for declaring variable types inline currently in use in core:

There are two standards for declaring local variable types inline currently in use in core, and a third standard that is under discussion as part of PSR-5. The Drupal project currently does not have a stated standard on how to document these variables; it should.

The three possible standards are:

1. Using a single asterisk and putting the variable name before the type. From \Drupal\node\Tests\NodeTokenReplaceTest::testNodeTokenReplacement:
   

    /* @var $node \Drupal\node\NodeInterface */
   

   This format is supported by Eclipse, Netbeans, PHPStorm and Zend Studio. If /** is substituted, orif the order is reversed it does not work in Netbeans (not sure about the other IDEs) as of this time (July 2014).

2. Using a double asterisk and putting the variable name after the type. From \Drupal\comment\CommentForm::submit():
   

     /** @var \Drupal\comment\CommentInterface $comment */
   

   This format is only supported by PHPStorm, as of July 2014.

3. Using a double asterisk and @type instead of @var, and optionally followed by a description. This is not yet used in core, so here's an arbitrary example:
   

     /** @type \Drupal\comment\CommentInterface $comment The comment */
   

   This is the proposed standard for PSR5, which has not yet been finalized as of July 2014.

There is a difference of opinion on whether we should be pragmatic and adopt #1 because it actually works now, or #2/#3, because they are more correct and consistent. If we adopt #1, we will most likely need to revise this standard if #3 or something similar is adopted as PSR-5, after IDEs adapt. If we adopt #2 or #3, then people who use some IDEs will not be able to benefit from it.