Validate "@var" comment

[aik099]

The correct @var comment looks like this:

/** @var ClassName $variable_name */
$variable_name = new ClassName();

Several things can be wrong here:

• comment placed under variable assignment:

$variable_name = new ClassName();
/** @var ClassName $variable_name */

• class name & variable name swapped:

/** @var $variable_name ClassName */
$variable_name = new ClassName();

• missing 2nd asterisk (turns T_DOC_BLOCK into regular T_COMMENT)

/* @var $variable_name ClassName */
$variable_name = new ClassName();

• variable name in comment doesn't match variable name in assignment on next line (if any found):

/** @var $another_variable_name ClassName */
$variable_name = new ClassName();

All of above can be combined.

Tricky case No. 1:

$supply_order =& $this->Application->recallObject(
    'supply-order.-item',
    null,
    array('skip_autoload' => true)
);
/** @var kDBItem $supply_order */

When we find ; on the above line, then we need to traverse up to statement start to figure out where to move the comment to.

[aik099]

To find matching variable:

1. find next T_VARIABLE (excluding T_WHITESPACE) that name marches @var comment
2. if not found or name doesn't match find previous T_VARIABLE (excluding T_WHITESPACE) that name marches @var comment
3. if not found, then we have no way of detecting if comment is placed correctly - ignore

[aik099]

variable name in comment doesn't match variable name in assignment on next line (if any found):

All except above supports auto-fixing.