Add @var $this comments to templates

[FiveDigital]

Templates contain comments like this:

/**
* Product view template
*
* @see Mage_Catalog_Block_Product_View
* @see Mage_Review_Block_Product_View
*/

Adding @var $this comments enables code completion in our IDEs:

/**
* Product view template
*
* @var $this Mage_Catalog_Block_Product_View
* @see Mage_Review_Block_Product_View
*/

[stalniy]

Not the best idea because template may be used by several blocks.
If you want to determine which template is related to some block class you may "Template Path Hits" (http://www.magentocommerce.com/blog/template-path-hints-tutorial-video/).

[FiveDigital]

Most templates are used by only one block. I have requested this because I'd like to be able to ctrl click function calls like $this->doSomething() in templates in my IDE.

[stalniy]

Anyway idea is bad. Just think, what will happen if somebody rewrites this block using Magento rewrite system?

[magento-team]

@FiveDigital
Thank you for proposing an interesting improvement.
Indeed, if to search among all PHTML templates in the system, notations @var $this and @see are already used ~50/50.
It does make sense to standardize block class(es) hinting. Proposal of declaring a primary block class using @var $this Primary_Block_Class and optionally additional classes using @see Additional_Block_Class has been sent to the technical leads for examination. As soon as there are any updates to the proposal state (rejected, accepted, adopted), corresponding update will be posted to the GutHub ticket.

@stalniy
Yes, you're right, that relation between blocks and templates is not 1 to 1, multiple blocks can utilize the same template. However, it does not contradict to the hinting of a primary and additional block classes.

[FiveDigital]

I know that @see is used in many templates, but that doesn't enable code completion/code hinting. I'm really a fan of being able to ctrl-click functions and I'm using this in templates, too. When we create/override templates for shop we develop in our company, I assure everyone add a @var $this comment. In fact, I'm always adding comments like /* @var $products Mage_Catalog_Model_Resource_Product_Collection everytime when writing code like $products = Mage::getResourceModel('catalog/product_collection') to be able to auto complete function and jump easily in the core code.

[magento-team]

The proposal was approved by the technical leads and included into Magento 2 coding standards. @var $this Primary_Block_Class is intended for primary class definition and @see Additional_Block_Class for additional classes. The task about updating exisitng templates was added to Magento 2 backlog.

@FiveDigital , thank you for the proposal.