Magento 1 PHPDoc syntax incorrect?

Question

I've noticed the following style PHPDoc declarations in Magento core code, and subsequently copied in Magento extensions:

/** @var $varName Mage_Core_Model_Example */

Should it not follow the @var [type] [$optionalName] [Optional comment] concept that PHPDoc uses? Eg:

/** @var Mage_Core_Model_Example $optionalVarNameOrComment Optional comment here */

Or more simply in practice:

/** @var Mage_Core_Model_Example */
$example = Mage::getModel('core/example');

---

Edit: maybe it's just inconsistency among their development team... I found an example of what I would consider a correct @var block while reviewing the EE 1.14.2 changes:

# app/code/core/Mage/Adminhtml/Model/Sales/Order/Create.php - 1531:
/** @var Mage_Sales_Model_Order $oldOrder */

Answer 1

You will not get a satisfactory answer unless there are Magento 1 coding regulations published somewhere.

However, Magento 1 follows the Zend Coding Standard, which in turn references to PHPDoc. So in theory, your observation is correct.

In practice, any regulations towards PHPDoc may not have been too strict, not forced by automatic validation. In consequence, developers did what worked depending on their IDE. PHPStorm supports both variations. Netbeans and Eclipse one and the other – t.b.c.

For Magento 2 there are published standards which explicitly allow both formats.