Mage_Catalog - DOC block update

[sreichel]

• doc blocks added/fixed
• PSR2 fixes (whitespaces, linebreaks, ...)

[colinmollenhour]

I think PHPStorm 2020.1 has gotten a little smarter, it now recognizes the auto-completion better in @sreichel's example. It recognizes (new B)->foo() as returning A|B. However, using @return $this everywhere it says (new B)->foo() only returns B which I believe is more accurate (although not significantly so).

However, using @sreichel's example, PHPStorm 2020.1 flags a warning on C:

Using only @return $this there are no errors.

In my opinion we should always use @return $this when a method effectively does return $this; and not use @inheritDoc since the IDE's just are not as smart with handling it.

[tmotyl]

I agree with @colinmollenhour, especially as return $this is understandable for a human, whithout the need to dig deeper, while inheridoc is not.

[sreichel]

However, using @sreichel's example, PHPStorm 2020.1 flags a warning on C:

Yes, it does. Just the tooltip is smarter.

In my opinion we should always use @return $this when a method effectively does return $this; and not use @inheritDoc since the IDE's just are not as smart with handling it.

Absolutely agree, but in this case its not return $this, it is parent::some() ....

But parent::_prepareLayout() just returns $this so @return $this is still correct - the return value is an instance of Mage_Catalog_Block_Layer_View.

---

I have used @inheritDoc only if return value calls parrent::x(), for return $this; i've used @return $this!

PLEASE leave it as it is for now.

[tmotyl]

I've resolved the conflict

[tmotyl]

conflict resolved once again

[tmotyl]

please revote

[kkrieger85]

LGFM

[colinmollenhour]

This is a step backward for type inference. @inheritDoc will mean that all methods added by Mage_Catalog_Model_Resource_Eav_Mysql4_Product_Action will no longer be detected by the IDE because the parent method's docs say the return is Mage_Core_Model_Mysql4_Abstract.

[tmotyl]

right. So what do you suggest?
do

     * @return Mage_Catalog_Model_Resource_Product_Action

?
Probably other places need to be rechecked

[sreichel]

I'd leave it as-is ...

• Mage_Catalog_Model_Resource_Eav_Mysql4_Product_Action is an empty deprecated class
• return parent::_getResource(); uses return type from parent DOCs ... so it seems correct
• @return Mage_Core_Model_Mysql4_Abstract should be changed to resource (later)

Problem is Mage_Core_Model_Abstract::_getResource() ...

return Mage::getResourceSingleton($this->_resourceName);

... neither IDE nor phpstan can detect correct child-model of Mage_Core_Model_Mysql4_Abstract.