Mage_Api - IDE improvements

app/code/core/Mage/Api/Controller/Action.php

@@ -32,11 +32,14 @@
 */
 class Mage_Api_Controller_Action extends Mage_Core_Controller_Front_Action
 {
+    /**
+     * @return $this
+     */
     public function preDispatch()
     {
         $this->getLayout()->setArea('adminhtml');
         Mage::app()->setCurrentStore('admin');
-        $this->setFlag('', self::FLAG_NO_START_SESSION, 1); // Do not start standart session
+        $this->setFlag('', self::FLAG_NO_START_SESSION, 1); // Do not start standard session
         parent::preDispatch();
         return $this;
     }

app/code/core/Mage/Api/Exception.php

@@ -35,7 +35,12 @@ class Mage_Api_Exception extends Mage_Core_Exception
 {
     protected $_customMessage = null;
 
-    public function __construct($faultCode, $customMessage=null)
+    /**
+     * Mage_Api_Exception constructor.
+     * @param string $faultCode
+     * @param string|null $customMessage
+     */
+    public function __construct($faultCode, $customMessage = null)
     {
         parent::__construct($faultCode);
         $this->_customMessage = $customMessage;
@@ -44,10 +49,10 @@ public function __construct($faultCode, $customMessage=null)
     /**
      * Custom error message, if error is not in api.
      *
-     * @return unknown
+     * @return string
      */
     public function getCustomMessage()
     {
         return $this->_customMessage;
     }
-} // Class Mage_Api_Model_Resource_Exception End
+}

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

@@ -57,7 +57,6 @@ public function isComplianceWSI()
      * Go through a WSI args array and turns it to correct state.
      *
      * @param Object $obj - Link to Object
-     * @return Object
      */
     public function wsiArrayUnpacker(&$obj)
     {
@@ -89,8 +88,8 @@ public function wsiArrayUnpacker(&$obj)
     /**
      * Go through an object parameters and unpack associative object to array.
      *
-     * @param Object $obj - Link to Object
-     * @return Object
+     * @param Object|array $obj - Link to Object
+     * @return bool
      */
     public function v2AssociativeArrayUnpacker(&$obj)
     {
@@ -167,7 +166,7 @@ public function associativeArrayUnpack(&$mixed)
      * Corrects data representation.
      *
      * @param Object $obj - Link to Object
-     * @return Object
+     * @return array
      */
     public function clearWsiFootprints(&$obj)
     {
@@ -222,10 +221,10 @@ public function wsiArrayPacker($mixed)
     /**
      * For response to the WSI, generates an object from array.
      *
-     * @param Array $arr - Link to Object
-     * @return Object
+     * @param array $arr - Link to Object
+     * @return stdClass
      */
-    public function packArrayToObject(Array $arr)
+    public function packArrayToObject(array $arr)
     {
         $obj = new stdClass();
         $obj->complexObjectArray = $arr;

app/code/core/Mage/Api/Helper/Object/Role.php

@@ -0,0 +1,10 @@
+<?php
+
+/**
+ * Class Mage_Api_Helper_Object_Role
+ *
+ * @method int getTreeLevel()
+ */
+class Mage_Api_Helper_Object_Role extends Varien_Object
+{
+}

app/code/core/Mage/Api/Helper/Object/Wsdl.php

@@ -0,0 +1,15 @@
+<?php
+
+/**
+ * Class Mage_Api_Object_Wsdl
+ *
+ * @method string getName()
+ * @method $this setName(string $value)
+ * @method $this setHandler(string $value)
+ * @method string getUrl()
+ * @method $this setUrl(string $value)
+ * @method string getWsdlContent()
+ */
+class Mage_Api_Helper_Object_Wsdl extends Varien_Object
+{
+}

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

@@ -91,8 +91,8 @@ protected function _getRoleRegistry()
     /**
      * Add parent to role object
      *
-     * @param Zend_Acl_Role $role
-     * @param Zend_Acl_Role $parent
+     * @param Zend_Acl_Role_Interface|string $role
+     * @param array|Zend_Acl_Role_Interface|string $parent
      * @return $this
      */
     public function addRoleParent($role, $parent)

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

@@ -37,9 +37,9 @@ class Mage_Api_Model_Acl_Assert_Ip implements Zend_Acl_Assert_Interface
     /**
      * Check whether ip is allowed
      *
-     * @param Zend_Acl $acl
-     * @param Zend_Acl_Role_Interface $role
-     * @param Zend_Acl_Resource_Interface $resource
+     * @param Mage_Api_Model_Acl $acl
+     * @param Mage_Api_Model_Acl_Role $role
+     * @param Mage_Api_Model_Acl_Resource $resource
      * @param string $privilege
      * @return boolean
      */
@@ -49,6 +49,9 @@ public function assert(Mage_Api_Model_Acl $acl, Mage_Api_Model_Acl_Role $role =
         return $this->_isCleanIP(Mage::helper('core/http')->getRemoteAddr());
     }
 
+    /**
+     * @param $ip
+     */
     protected function _isCleanIP($ip)
     {
         // ...

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

@@ -37,9 +37,9 @@ class Mage_Api_Model_Acl_Assert_Time implements Zend_Acl_Assert_Interface
     /**
      * Assert time
      *
-     * @param Zend_Acl $acl
-     * @param Zend_Acl_Role_Interface $role
-     * @param Zend_Acl_Resource_Interface $resource
+     * @param Mage_Api_Model_Acl $acl
+     * @param Mage_Api_Model_Acl_Role $role
+     * @param Mage_Api_Model_Acl_Resource $resource
      * @param string $privilege
      * @return boolean
      */
@@ -49,6 +49,9 @@ public function assert(Mage_Api_Model_Acl $acl, Mage_Api_Model_Acl_Role $role =
         return $this->_isCleanTime(time());
     }
 
+    /**
+     * @param $time
+     */
     protected function _isCleanTime($time)
     {
         // ...

app/code/core/Mage/Api/Model/Acl/Role/Registry.php

@@ -39,7 +39,7 @@ class Mage_Api_Model_Acl_Role_Registry extends Zend_Acl_Role_Registry
      *
      * @param Zend_Acl_Role_Interface|string $role
      * @param array|Zend_Acl_Role_Interface|string $parents
-     * @return Mage_Auth_Model_Acl_Role_Registry
+     * @return $this
      */
     function addParent($role, $parents)
     {

app/code/core/Mage/Api/Model/Config.php

@@ -36,11 +36,9 @@ class Mage_Api_Model_Config extends Varien_Simplexml_Config
     const CACHE_TAG         = 'config_api';
 
     /**
-     * Constructor
-     *
-     * @see Varien_Simplexml_Config
+     * @inheritDoc
      */
-    public function __construct($sourceData=null)
+    public function __construct($sourceData = null)
     {
         $this->setCacheId('config_api');
         $this->setCacheTags(array(self::CACHE_TAG));
@@ -99,7 +97,7 @@ public function getAdapters()
     {
         $adapters = array();
         foreach ($this->getNode('adapters')->children() as $adapterName => $adapter) {
-            /* @var $adapter Varien_SimpleXml_Element */
+            /* @var Varien_SimpleXml_Element $adapter */
             if (isset($adapter->use)) {
                 $adapter = $this->getNode('adapters/' . (string) $adapter->use);
             }
@@ -138,7 +136,7 @@ public function getActiveAdapters()
     /**
      * Retrieve handlers
      *
-     * @return Varien_Simplexml_Element
+     * @return SimpleXMLElement
      */
     public function getHandlers()
     {
@@ -148,7 +146,7 @@ public function getHandlers()
     /**
      * Retrieve resources
      *
-     * @return Varien_Simplexml_Element
+     * @return SimpleXMLElement
      */
     public function getResources()
     {
@@ -158,7 +156,7 @@ public function getResources()
     /**
      * Retrieve resources alias
      *
-     * @return Varien_Simplexml_Element
+     * @return SimpleXMLElement
      */
     public function getResourcesAlias()
     {
@@ -174,7 +172,7 @@ public function getResourcesAlias()
      * @param string $parentName
      * @return $this
      */
-    public function loadAclResources(Mage_Api_Model_Acl $acl, $resource=null, $parentName=null)
+    public function loadAclResources(Mage_Api_Model_Acl $acl, $resource = null, $parentName = null)
     {
         $resourceName = null;
         if (is_null($resource)) {
@@ -202,7 +200,7 @@ public function loadAclResources(Mage_Api_Model_Acl $acl, $resource=null, $paren
      * Get acl assert config
      *
      * @param string $name
-     * @return Mage_Core_Model_Config_Element|boolean
+     * @return bool|Mage_Core_Model_Config_Element|SimpleXMLElement
      */
     public function getAclAssert($name='')
     {
@@ -222,12 +220,12 @@ public function getAclAssert($name='')
      * Retrieve privilege set by name
      *
      * @param string $name
-     * @return Mage_Core_Model_Config_Element|boolean
+     * @return bool|Mage_Core_Model_Config_Element|SimpleXMLElement
      */
-    public function getAclPrivilegeSet($name='')
+    public function getAclPrivilegeSet($name = '')
     {
         $sets = $this->getNode('acl/privilegeSets');
-        if (''===$name) {
+        if ('' === $name) {
             return $sets;
         }
 
@@ -238,7 +236,11 @@ public function getAclPrivilegeSet($name='')
         return false;
     }
 
-    public function getFaults($resourceName=null)
+    /**
+     * @param string|null $resourceName
+     * @return array
+     */
+    public function getFaults($resourceName = null)
     {
         if (is_null($resourceName)
             || !isset($this->getResources()->$resourceName)
@@ -247,7 +249,7 @@ public function getFaults($resourceName=null)
         } else {
             $faultsNode = $this->getResources()->$resourceName->faults;
         }
-        /* @var $faultsNode Varien_Simplexml_Element */
+        /* @var Varien_Simplexml_Element $faultsNode */
 
         $translateModule = 'api';
         if (isset($faultsNode['module'])) {
@@ -268,23 +270,38 @@ public function getFaults($resourceName=null)
     /**
      * Retrieve cache object
      *
-     * @return Zend_Cache_Frontend_File
+     * @return Zend_Cache_Core
      */
     public function getCache()
     {
         return Mage::app()->getCache();
     }
 
+    /**
+     * @param string $id
+     * @return bool|mixed
+     */
     protected function _loadCache($id)
     {
         return Mage::app()->loadCache($id);
     }
 
+    /**
+     * @param string $data
+     * @param string $id
+     * @param array $tags
+     * @param bool $lifetime
+     * @return bool|Mage_Core_Model_App
+     */
     protected function _saveCache($data, $id, $tags=array(), $lifetime=false)
     {
         return Mage::app()->saveCache($data, $id, $tags, $lifetime);
     }
 
+    /**
+     * @param string $id
+     * @return Mage_Core_Model_App
+     */
     protected function _removeCache($id)
     {
         return Mage::app()->removeCache($id);

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

@@ -97,8 +97,10 @@ protected function _getServer()
      * Dispatches fault
      *
      * @param string $code
+     * @param string|null $customMessage
+     * @throws Mage_Api_Exception
      */
-    protected function _fault($code, $customMessage=null)
+    protected function _fault($code, $customMessage = null)
     {
         throw new Mage_Api_Exception($code, $customMessage);
     }

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

@@ -78,13 +78,13 @@ public function loadAcl()
      * Load roles
      *
      * @param Mage_Api_Model_Acl $acl
-     * @param array $rolesArr
+     * @param array[] $rolesArr
      * @return $this
      */
     public function loadRoles(Mage_Api_Model_Acl $acl, array $rolesArr)
     {
         foreach ($rolesArr as $role) {
-            $parent = $role['parent_id']>0 ? Mage_Api_Model_Acl::ROLE_TYPE_GROUP.$role['parent_id'] : null;
+            $parent = $role['parent_id']>0 ? Mage_Api_Model_Acl::ROLE_TYPE_GROUP.$role['parent_id'] : '';
             switch ($role['role_type']) {
                 case Mage_Api_Model_Acl::ROLE_TYPE_GROUP:
                     $roleId = $role['role_type'].$role['role_id'];

app/code/core/Mage/Api/Model/Resource/Acl/Role.php

@@ -28,6 +28,8 @@
 /**
  * ACL role resource
  *
+ * @method $this setCreated(string $value)
+ *
  * @category    Mage
  * @package     Mage_Api
  * @author      Magento Core Team <core@magentocommerce.com>

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

@@ -46,7 +46,7 @@ protected function _construct()
     /**
      * Action before save
      *
-     * @param Mage_Core_Model_Abstract $object
+     * @param Mage_Core_Model_Abstract|Mage_Api_Model_Role $object
      * @return $this
      */
     protected function _beforeSave(Mage_Core_Model_Abstract $object)
@@ -59,12 +59,7 @@ protected function _beforeSave(Mage_Core_Model_Abstract $object)
     }
 
     /**
-     * Load an object
-     *
-     * @param Mage_Core_Model_Abstract $object
-     * @param mixed $value
-     * @param string $field field to load by (defaults to model id)
-     * @return Mage_Core_Model_Resource_Db_Abstract
+     * @inheritDoc
      */
     public function load(Mage_Core_Model_Abstract $object, $value, $field = null)
     {

app/code/core/Mage/Api/Model/Resource/Role/Collection.php

@@ -46,7 +46,7 @@ protected function _construct()
     /**
      * Aet user filter
      *
-     * @param int $userId
+     * @param int|string $userId
      * @return $this
      */
     public function setUserFilter($userId)