Mage_Api - DOC block update

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,12 +57,10 @@ 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)
     {
         if (is_object($obj)) {
-
             $modifiedKeys = $this->clearWsiFootprints($obj);
 
             foreach ($obj as $value) {
@@ -89,8 +87,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 +165,7 @@ public function associativeArrayUnpack(&$mixed)
      * Corrects data representation.
      *
      * @param Object $obj - Link to Object
-     * @return Object
+     * @return array
      */
     public function clearWsiFootprints(&$obj)
     {
@@ -222,10 +220,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/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,18 +37,24 @@ 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
      */
-    public function assert(Mage_Api_Model_Acl $acl, Mage_Api_Model_Acl_Role $role = null,
-                           Mage_Api_Model_Acl_Resource $resource = null, $privilege = null)
-    {
+    public function assert(
+        Mage_Api_Model_Acl $acl,
+        Mage_Api_Model_Acl_Role $role = null,
+        Mage_Api_Model_Acl_Resource $resource = null,
+        $privilege = null
+    ) {
         return $this->_isCleanIP(Mage::helper('core/http')->getRemoteAddr());
     }
 
+    /**
+     * @param bool $ip
+     */
     protected function _isCleanIP($ip)
     {
         // ...

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

@@ -37,18 +37,24 @@ 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
      */
-    public function assert(Mage_Api_Model_Acl $acl, Mage_Api_Model_Acl_Role $role = null,
-                           Mage_Api_Model_Acl_Resource $resource = null, $privilege = null)
-    {
+    public function assert(
+        Mage_Api_Model_Acl $acl,
+        Mage_Api_Model_Acl_Role $role = null,
+        Mage_Api_Model_Acl_Resource $resource = null,
+        $privilege = null
+    ) {
         return $this->_isCleanTime(time());
     }
 
+    /**
+     * @param bool $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);
             }
@@ -122,7 +120,7 @@ public function getActiveAdapters()
             }
 
             if (isset($adapter->required) && isset($adapter->required->extensions)) {
-                foreach ($adapter->required->extensions->children() as $extension=>$data) {
+                foreach ($adapter->required->extensions->children() as $extension => $data) {
                     if (!extension_loaded($extension)) {
                         continue;
                     }
@@ -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,9 +200,9 @@ 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='')
+    public function getAclAssert($name = '')
     {
         $asserts = $this->getNode('acl/asserts');
         if (''===$name) {
@@ -222,9 +220,9 @@ 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) {
@@ -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,11 +249,11 @@ 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'])) {
-           $translateModule = (string) $faultsNode['module'];
+            $translateModule = (string) $faultsNode['module'];
         }
 
         $faults = array();
@@ -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);
     }
 
-    protected function _saveCache($data, $id, $tags=array(), $lifetime=false)
+    /**
+     * @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,9 +97,11 @@ 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);
     }
-} // Class Mage_Api_Model_Resource_Abstract End
+}

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

@@ -69,7 +69,8 @@ public function loadAcl()
                     array('a'=>$this->getTable('api/assert')),
                     'a.assert_id=r.assert_id',
                     array('assert_type', 'assert_data')
-                ));
+                )
+        );
         $this->loadRules($acl, $rulesArr);
         return $acl;
     }
@@ -78,7 +79,7 @@ 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)
@@ -127,7 +128,7 @@ public function loadRules(Mage_Api_Model_Acl $acl, array $rulesArr)
             try {
                 if ($rule['api_permission'] == 'allow') {
                     $acl->allow($role, $resource, $privileges, $assert);
-                } else if ($rule['api_permission'] == 'deny') {
+                } elseif ($rule['api_permission'] == 'deny') {
                     $acl->deny($role, $resource, $privileges, $assert);
                 }
             } catch (Exception $e) {

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>