Some fixes for phpdocs (#2588)

* Some phpdocs updates

* Minor fixes

Co-authored-by: Fabrizio Balliano <fabrizio.balliano@gmail.com>

app/code/core/Mage/Admin/Model/Acl/Assert/Ip.php

@@ -31,10 +31,10 @@ class Mage_Admin_Model_Acl_Assert_Ip implements Zend_Acl_Assert_Interface
      * Check whether ip is allowed
      *
      * @param Mage_Admin_Model_Acl $acl
-     * @param Mage_Admin_Model_Acl_Role $role
-     * @param Mage_Admin_Model_Acl_Resource $resource
-     * @param string $privilege
-     * @return bool
+     * @param Mage_Admin_Model_Acl_Role|null $role
+     * @param Mage_Admin_Model_Acl_Resource|null $resource
+     * @param string|null $privilege
+     * @return bool|null
      */
     public function assert(
         Mage_Admin_Model_Acl $acl,

app/code/core/Mage/Admin/Model/Acl/Assert/Time.php

@@ -31,10 +31,10 @@ class Mage_Admin_Model_Acl_Assert_Time implements Zend_Acl_Assert_Interface
      * Assert time
      *
      * @param Mage_Admin_Model_Acl $acl
-     * @param Mage_Admin_Model_Acl_Role $role
-     * @param Mage_Admin_Model_Acl_Resource $resource
-     * @param string $privilege
-     * @return bool
+     * @param Mage_Admin_Model_Acl_Role|null $role
+     * @param Mage_Admin_Model_Acl_Resource|null $resource
+     * @param string|null $privilege
+     * @return bool|null
      */
     public function assert(
         Mage_Admin_Model_Acl $acl,

app/code/core/Mage/Admin/Model/Redirectpolicy.php

@@ -45,7 +45,7 @@ public function __construct($parameters = [])
      * Redirect to startup page after logging in if request contains any params (except security key)
      *
      * @param Mage_Admin_Model_User $user
-     * @param Zend_Controller_Request_Http $request
+     * @param Zend_Controller_Request_Http|null $request
      * @param string|null $alternativeUrl
      * @return null|string
      */

app/code/core/Mage/Adminhtml/Block/Catalog/Product/Composite/Configure.php

@@ -57,7 +57,7 @@ public function getProduct()
     /**
      * Set product object
      *
-     * @param Mage_Catalog_Model_Product $product
+     * @param Mage_Catalog_Model_Product|null $product
      * @return $this
      */
     public function setProduct(Mage_Catalog_Model_Product $product = null)

app/code/core/Mage/Adminhtml/Block/Customer/Edit/Tab/Wishlist.php

@@ -192,7 +192,6 @@ public function getGridUrl()
      */
     protected function _addColumnFilterToCollection($column)
     {
-        /** @var Mage_Wishlist_Model_Resource_Item_Collection $collection */
         $collection = $this->getCollection();
         $value = $column->getFilter()->getValue();
         if ($collection && $value) {

app/code/core/Mage/Adminhtml/Block/System/Config/Form/Field/Array/Abstract.php

@@ -135,7 +135,7 @@ public function getArrayRows()
             return $this->_arrayRowsCache;
         }
         $result = [];
-        /** @var Varien_Data_Form_Element_Abstract */
+        /** @var Varien_Data_Form_Element_Abstract $element */
         $element = $this->getElement();
         if ($element->getValue() && is_array($element->getValue())) {
             foreach ($element->getValue() as $rowId => $row) {

app/code/core/Mage/Adminhtml/Block/System/Convert/Gui/Edit/Tabs.php

@@ -67,8 +67,7 @@ protected function _beforeToHtml()
                 'content'   => $this->getLayout()->createBlock('adminhtml/system_convert_profile_edit_tab_run')->toHtml(),
             ]);
 
-            /** @var Mage_Adminhtml_Block_System_Convert_Gui_Edit_Tab_View
-            $block */
+            /** @var Mage_Adminhtml_Block_System_Convert_Gui_Edit_Tab_View $block */
             $block = $this->getLayout()->createBlock('adminhtml/system_convert_gui_edit_tab_view');
             $this->addTab('view', [
                 'label'     => Mage::helper('adminhtml')->__('Profile Actions XML'),

app/code/core/Mage/Adminhtml/Model/Sales/Order/Create.php

@@ -1663,7 +1663,7 @@ protected function _getNewCustomerEmail($customer)
     protected function _putCustomerIntoQuote()
     {
         if (!$this->getSession()->getCustomer()->getId()) {
-            /** @var Mage_Customer_Model_Customer*/
+            /** @var Mage_Customer_Model_Customer $customer */
             $customer = Mage::getModel('customer/customer');
 
             $customer->addData($this->getBillingAddress()->exportCustomerAddress()->getData())

app/code/core/Mage/Adminhtml/controllers/Sales/Order/CreateController.php

@@ -475,8 +475,6 @@ public function cancelAction()
 
     /**
      * Saving quote and create order
-     *
-     * @throws Mage_Core_Exception
      */
     public function saveAction()
     {

app/code/core/Mage/Api/Model/Acl/Assert/Ip.php

@@ -31,10 +31,10 @@ class Mage_Api_Model_Acl_Assert_Ip implements Zend_Acl_Assert_Interface
      * Check whether ip is allowed
      *
      * @param Mage_Api_Model_Acl $acl
-     * @param Mage_Api_Model_Acl_Role $role
-     * @param Mage_Api_Model_Acl_Resource $resource
-     * @param string $privilege
-     * @return bool
+     * @param Mage_Api_Model_Acl_Role|null $role
+     * @param Mage_Api_Model_Acl_Resource|null $resource
+     * @param string|null $privilege
+     * @return bool|null
      */
     public function assert(
         Mage_Api_Model_Acl $acl,

app/code/core/Mage/Api/Model/Acl/Assert/Time.php

@@ -31,10 +31,10 @@ class Mage_Api_Model_Acl_Assert_Time implements Zend_Acl_Assert_Interface
      * Assert time
      *
      * @param Mage_Api_Model_Acl $acl
-     * @param Mage_Api_Model_Acl_Role $role
-     * @param Mage_Api_Model_Acl_Resource $resource
-     * @param string $privilege
-     * @return bool
+     * @param Mage_Api_Model_Acl_Role|null $role
+     * @param Mage_Api_Model_Acl_Resource|null $resource
+     * @param string|null $privilege
+     * @return bool|null
      */
     public function assert(
         Mage_Api_Model_Acl $acl,

app/code/core/Mage/Api/Model/Server/Wsi/Handler.php

@@ -40,7 +40,7 @@ public function __call($function, $args)
     {
         $args = $args[0];
 
-        /** @var Mage_Api_Helper_Data */
+        /** @var Mage_Api_Helper_Data $helper */
         $helper = Mage::helper('api/data');
 
         $helper->wsiArrayUnpacker($args);

app/code/core/Mage/Api2/Model/Multicall.php

@@ -95,7 +95,6 @@ protected function _callSubresource($subresource)
      *
      * @param Mage_Core_Model_Config_Element $subresource
      * @param array $requestData
-     * @throws Mage_Api2_Exception
      * @return $this
      */
     protected function _internalCall($subresource, $requestData)

app/code/core/Mage/Api2/Model/Route/ApiType.php

@@ -41,7 +41,7 @@ class Mage_Api2_Model_Route_ApiType extends Mage_Api2_Model_Route_Abstract imple
      * @param string $route Map used to match with later submitted URL path
      * @param array $defaults Defaults for map variables with keys as variable names
      * @param array $reqs Regular expression requirements for variables (keys as variable names)
-     * @param Zend_Translate $translator Translator to use for this instance
+     * @param Zend_Translate|null $translator Translator to use for this instance
      * @param mixed $locale
      */
     public function __construct(

app/code/core/Mage/Bundle/Helper/Catalog/Product/Configuration.php

@@ -87,9 +87,7 @@ public function getBundleOptions(Mage_Catalog_Model_Product_Configuration_Item_I
         $optionsQuoteItemOption = $item->getOptionByCode('bundle_option_ids');
         $bundleOptionsIds = $optionsQuoteItemOption ? unserialize($optionsQuoteItemOption->getValue(), ['allowed_classes' => false]) : [];
         if ($bundleOptionsIds) {
-            /**
-            * @var Mage_Bundle_Model_Resource_Option_Collection
-            */
+            /** @var Mage_Bundle_Model_Resource_Option_Collection $bundleOptionsIds */
             $optionsCollection = $typeInstance->getOptionsByIds($bundleOptionsIds, $product);
 
             // get and add bundle selections collection

app/code/core/Mage/Bundle/Model/Observer.php

@@ -107,7 +107,6 @@ public function appendUpsellProducts($observer)
             return $this;
         }
 
-        /** @var Mage_Catalog_Model_Resource_Product_Collection $bundleCollection */
         $bundleCollection = $product->getCollection()
             ->addAttributeToSelect(Mage::getSingleton('catalog/config')->getProductAttributes())
             ->addStoreFilter()

app/code/core/Mage/Bundle/Model/Product/Type.php

@@ -580,7 +580,6 @@ protected function _prepareProduct(Varien_Object $buyRequest, $product, $process
                 // Check if added selections are still on sale
                 foreach ($selections->getItems() as $key => $selection) {
                     if (!$selection->isSalable() && !$skipSaleableCheck) {
-                        /** @var Mage_Bundle_Model_Option $_option */
                         $_option = $optionsCollection->getItemById($selection->getOptionId());
                         if (is_array($options[$_option->getId()]) && count($options[$_option->getId()]) > 1) {
                             $moreSelections = true;

app/code/core/Mage/Catalog/Block/Product/View/Options.php

@@ -64,7 +64,7 @@ public function getProduct()
     /**
      * Set product object
      *
-     * @param Mage_Catalog_Model_Product $product
+     * @param Mage_Catalog_Model_Product|null $product
      * @return $this
      */
     public function setProduct(Mage_Catalog_Model_Product $product = null)

app/code/core/Mage/Catalog/Block/Product/View/Options/Abstract.php

@@ -44,8 +44,8 @@ abstract class Mage_Catalog_Block_Product_View_Options_Abstract extends Mage_Cor
     /**
      * Set Product object
      *
-     * @param Mage_Catalog_Model_Product $product
-     * @return Mage_Catalog_Block_Product_View_Options_Abstract
+     * @param Mage_Catalog_Model_Product|null $product
+     * @return $this
      */
     public function setProduct(Mage_Catalog_Model_Product $product = null)
     {

app/code/core/Mage/Catalog/Helper/Product/Configuration.php

@@ -118,9 +118,7 @@ public function getGroupedOptions(Mage_Catalog_Model_Product_Configuration_Item_
         }
 
         $options = [];
-        /**
-         * @var Mage_Catalog_Model_Product_Type_Grouped
-         */
+        /** @var Mage_Catalog_Model_Product_Type_Grouped $typeInstance */
         $typeInstance = $product->getTypeInstance(true);
         $associatedProducts = $typeInstance->getAssociatedProducts($product);
 

app/code/core/Mage/Catalog/Model/Api2/Product/Image/Rest/Admin/V1.php

@@ -197,7 +197,6 @@ protected function _delete()
     /**
      * Retrieve product images data
      *
-     * @throws Mage_Api2_Exception
      * @return array
      */
     protected function _retrieveCollection()

app/code/core/Mage/Catalog/Model/Product/Compare/Item.php

@@ -180,7 +180,7 @@ public function bindCustomerLogin()
     /**
      * Customer logout bind process
      *
-     * @param Varien_Event_Observer $observer
+     * @param Varien_Event_Observer|null $observer
      * @return $this
      */
     public function bindCustomerLogout(Varien_Event_Observer $observer = null)

app/code/core/Mage/Catalog/Model/Product/Option.php

@@ -265,7 +265,7 @@ public function getProduct()
     /**
      * Set product instance
      *
-     * @param Mage_Catalog_Model_Product $product
+     * @param Mage_Catalog_Model_Product|null $product
      * @return $this
      */
     public function setProduct(Mage_Catalog_Model_Product $product = null)

app/code/core/Mage/Catalog/Model/Product/Option/Type/Select.php

@@ -60,8 +60,7 @@ public function validateUserValue($values)
     /**
      * Prepare option value for cart
      *
-     * @throws Mage_Core_Exception
-     * @return mixed Prepared option value
+     * @return array|int|string|null Prepared option value
      */
     public function prepareForCart()
     {

app/code/core/Mage/Catalog/Model/Resource/Category/Indexer/Product.php

@@ -313,8 +313,9 @@ public function catalogCategorySave(Mage_Index_Model_Event $event)
     /**
      * Reindex not anchor root categories
      *
-     * @param array $categoryIds
+     * @param array|null $categoryIds
      * @return $this
+     * @throws Zend_Db_Adapter_Exception
      */
     protected function _refreshNotAnchorRootCategories(array $categoryIds = null)
     {

app/code/core/Mage/Catalog/Model/Resource/Product/Collection.php

@@ -329,7 +329,6 @@ public function isEnabledFlat()
         }
         $storeId = $this->getStoreId();
         if (!isset($this->_flatEnabled[$storeId])) {
-            /** @var Mage_Catalog_Helper_Product_Flat $flatHelper */
             $flatHelper = $this->getFlatHelper();
             $this->_flatEnabled[$storeId] = $flatHelper->isAccessible() && $flatHelper->isBuilt($storeId);
         }

app/code/core/Mage/Centinel/Model/Service.php

@@ -77,7 +77,6 @@ protected function _getSession()
     /**
      * Return value from section of centinel config
      *
-     * @param string $path
      * @return string
      */
     protected function _getConfig()

app/code/core/Mage/Checkout/Model/Api/Resource.php

@@ -166,7 +166,7 @@ protected function _updateAttributes($data, $object, $type, array $attributes =
      *
      * @param Mage_Core_Model_Abstract $object
      * @param string $type
-     * @param array $attributes
+     * @param array|null $attributes
      * @return array
      */
     protected function _getAttributes($object, $type, array $attributes = null)
@@ -205,7 +205,7 @@ protected function _getAttributes($object, $type, array $attributes = null)
      *
      * @param string $attributeCode
      * @param string $type
-     * @param array $attributes
+     * @param array|null $attributes
      * @return bool
      */
     protected function _isAllowedAttribute($attributeCode, $type, array $attributes = null)

app/code/core/Mage/Cms/Model/Wysiwyg/Images/Storage.php

@@ -110,7 +110,6 @@ public function getFilesCollection($path, $type = null)
             }
         }
 
-        /** @var Varien_Data_Collection_Filesystem $collection */
         $collection = $this->getCollection($path)
             ->setCollectDirs(false)
             ->setCollectFiles(true)

app/code/core/Mage/Core/Controller/Request/Http.php

@@ -82,7 +82,7 @@ class Mage_Core_Controller_Request_Http extends Zend_Controller_Request_Http
      * This value is calculated instead of reading PATH_INFO
      * directly from $_SERVER due to cross-platform differences.
      *
-     * @return string
+     * @return string 'something.html'|'/'|'/path0'|'/path0/path1/'|'/path0/path1/path2'|etc
      */
     public function getOriginalPathInfo()
     {
@@ -237,7 +237,6 @@ public function getDirectFrontNames()
 
     /**
      * @return Zend_Controller_Request_Http
-     * @throws Zend_Controller_Request_Exception
      */
     public function getOriginalRequest()
     {

app/code/core/Mage/Core/Controller/Varien/Front.php

@@ -390,7 +390,6 @@ protected function _isAdminFrontNameMatched($request)
 
         if (is_array($adminFrontNameNodes)) {
             foreach ($adminFrontNameNodes as $frontNameNode) {
-                /** @var SimpleXMLElement $frontNameNode */
                 $adminFrontNames[] = (string)$frontNameNode;
             }
         }

app/code/core/Mage/Core/Model/Url/Rewrite.php

@@ -207,8 +207,8 @@ public function removeTag($tags)
     /**
      * Implement logic of custom rewrites
      *
-     * @param Zend_Controller_Request_Http $request
-     * @param Zend_Controller_Response_Http $response
+     * @param Zend_Controller_Request_Http|null $request
+     * @param Zend_Controller_Response_Http|null $response
      * @return bool
      * @throws Mage_Core_Model_Store_Exception
      * @deprecated since 1.7.0.2. Refactored and moved to Mage_Core_Controller_Request_Rewrite

app/code/core/Mage/Customer/Block/Form/Login.php

@@ -109,7 +109,6 @@ public function canShowLogin()
         if (Mage::getStoreConfigFlag(Mage_Customer_Helper_Data::XML_PATH_CUSTOMER_STARTUP_REDIRECT_TO_DASHBOARD)) {
             $url = Mage::helper('customer')->getDashboardUrl();
         } else {
-            /** @var string $pathInfo 'something.html'|'/'|'/path0'|'/path0/path1/'|'/path0/path1/path2'|etc */
             $pathInfo = $this->getRequest()->getOriginalPathInfo();
             if (strtolower(substr($pathInfo, -5)) === '.html') {
                 // For URL rewrite, preserve the path without considering query or post.

app/code/core/Mage/Customer/Model/Api/Resource.php

@@ -45,7 +45,7 @@ class Mage_Customer_Model_Api_Resource extends Mage_Api_Model_Resource_Abstract
      * Check is attribute allowed
      *
      * @param Mage_Eav_Model_Entity_Attribute_Abstract $attribute
-     * @param array $filter
+     * @param array|null $filter
      * @return bool
      */
     protected function _isAllowedAttribute($attribute, array $filter = null)
@@ -64,7 +64,7 @@ protected function _isAllowedAttribute($attribute, array $filter = null)
      * Return list of allowed attributes
      *
      * @param Mage_Eav_Model_Entity_Abstract $entity
-     * @param array $filter
+     * @param array|null $filter
      * @return array
      */
     public function getAllowedAttributes($entity, array $filter = null)

app/code/core/Mage/Directory/Helper/Data.php

@@ -196,7 +196,6 @@ protected function _getRegions($storeId)
 
         /** @var Mage_Directory_Model_Region $regionModel */
         $regionModel = $this->_factory->getModel('directory/region');
-        /** @var Mage_Directory_Model_Resource_Region_Collection $collection */
         $collection = $regionModel->getResourceCollection()
             ->addCountryFilter($countryIds)
             ->load();

app/code/core/Mage/Directory/sql/directory_setup/mysql4-upgrade-0.8.8-0.8.9.php

@@ -21,7 +21,7 @@
 /** @var Mage_Core_Model_Resource_Setup $this */
 $installer = $this;
 
-/** @var Varien_Db_Adapter_Pdo_Mysql */
+/** @var Varien_Db_Adapter_Pdo_Mysql $connection */
 $connection  = $this->getConnection();
 
 $regionTable = $installer->getTable('directory/country_region');

app/code/core/Mage/Directory/sql/directory_setup/mysql4-upgrade-0.8.9-0.8.10.php

@@ -21,7 +21,7 @@
 /** @var Mage_Core_Model_Resource_Setup $this */
 $installer = $this;
 
-/** @var Varien_Db_Adapter_Pdo_Mysql */
+/** @var Varien_Db_Adapter_Pdo_Mysql $connection */
 $connection   = $this->getConnection();
 
 $regionTable  = $installer->getTable('directory/country_region');

app/code/core/Mage/Eav/Model/Resource/Entity/Attribute.php

@@ -174,7 +174,7 @@ protected function _beforeSave(Mage_Core_Model_Abstract $object)
     /**
      * Save additional attribute data after save attribute
      *
-     * @param Mage_Eav_Model_Entity_Attribute|Mage_Eav_Model_Entity_Attribute $object
+     * @param Mage_Eav_Model_Entity_Attribute $object
      * @inheritDoc
      */
     protected function _afterSave(Mage_Core_Model_Abstract $object)