Add more documentation

Author: Jamie Snape

core/controllers/ApikeyController.php

@@ -21,14 +21,20 @@
 /** Apikey controller for Web Api */
 class ApikeyController extends AppController
 {
+    /** @var array */
     public $_models = array('User', 'Userapi');
+
+    /** @var array */
     public $_forms = array('Apikey');
+
+    /** @var array */
     public $_components = array('Date');
 
     /**
      * Configuration action for a user's api keys
      *
      * @param userId The id of the user to display
+     * @throws Zend_Exception
      */
     public function usertabAction()
     {

core/controllers/BrowseController.php

@@ -491,6 +491,7 @@ public function getelementinfoAction()
      * @param type The type of the resource: (folder | item)
      * @return JSON object with the "policy" field set to the max policy on the resource.
      *              Throws exception if the user has no access to the resource
+     * @throws Zend_Exception
      */
     public function getmaxpolicyAction()
     {

core/controllers/CommunityController.php

@@ -467,6 +467,7 @@ public function deleteAction()
      * Dialog for inviting a user to a community
      *
      * @param communityId Id of the community to invite into. Write permission required.
+     * @throws Zend_Exception
      */
     public function invitationAction()
     {
@@ -536,6 +537,7 @@ public function addusertogroupAction()
      * @param [userId] Id of the user to invite. If not passed, must pass email parameter
      * @param [email] Email of the user to invite.  If not passed, must pass userId parameter.
      * If no such user exists, sends an email inviting the user to register and join the group.
+     * @throws Zend_Exception
      */
     public function sendinvitationAction()
     {
@@ -839,6 +841,7 @@ public function removeuserfromgroupAction()
      * Requires moderator or admin permission on the community
      *
      * @param communityId The id of the community
+     * @throws Zend_Exception
      */
     public function selectgroupAction()
     {

core/controllers/DownloadController.php

@@ -23,11 +23,14 @@
  */
 class DownloadController extends AppController
 {
+    /** @var array */
     public $_models = array('Folder', 'Item', 'Community', 'User', 'Bitstream');
-    public $_daos = array();
+
+    /** @var array */
     public $_components = array('DownloadBitstream');
 
-    /** index
+    /**
+     * Index action.
      *
      * @param folders = 12-13 (will download a zip of the folder 12 and 13, recursively)
      * @param folders = 12, 1-13, 1 (will download a zip of the folder 12 and 13, recursively) // Need testing
@@ -37,6 +40,7 @@ class DownloadController extends AppController
      * @param bitstream = 1 (will download related bitstream)
      * @param offset The offset in bytes if downloading a bitstream (defaults to 0)
      * @param name Alternate filename when downloading a bitstream (defaults to bitstream name)
+     * @throws Zend_Exception
      */
     public function indexAction()
     {
@@ -223,6 +227,8 @@ public function indexAction()
 
     /**
      * Ajax action for determining what action to take based on the size of the requested download.
+     *
+     * @throws Zend_Exception
      */
     public function checksizeAction()
     {
@@ -288,6 +294,7 @@ public function checksizeAction()
      *   download/item/<item_id>/...
      * Any extra parameters are ignored and can be used to force clients like wget to download to the correct filename
      * if the content-disposition header is ignored by the user agent.
+     * @throws Zend_Exception
      */
     public function itemAction()
     {
@@ -304,6 +311,8 @@ public function itemAction()
      *   download/folder/<folder_id>/...
      * Any extra parameters are ignored and can be used to force clients like wget to download to the correct filename
      * if the content-disposition header is ignored by the user agent.
+     *
+     * @throws Zend_Exception
      */
     public function folderAction()
     {
@@ -320,6 +329,8 @@ public function folderAction()
      *   download/bitstream/<bitstream_id>/...
      * Any extra parameters are ignored and can be used to force clients like wget to download to the correct filename
      * if the content-disposition header is ignored by the user agent.
+     *
+     * @throws Zend_Exception
      */
     public function bitstreamAction()
     {

core/controllers/ItemController.php

@@ -574,6 +574,7 @@ public function checksharedAction()
      * @param metadatatype
      * @param element
      * @param qualifier
+     * @throws Zend_Exception
      */
     public function getmetadatavalueexistsAction()
     {
@@ -613,6 +614,7 @@ public function getmetadatavalueexistsAction()
      * otherwise the request produces no output.
      *
      * @param itemId The item whose thumbnail you wish to download
+     * @throws Zend_Exception
      */
     public function thumbnailAction()
     {

core/controllers/UserController.php

@@ -1199,6 +1199,7 @@ public function deletedialogAction()
      * @param [lastName] User's last name
      * @param [password] User's password
      * @param [password2] User's password retyped
+     * @throws Zend_Exception
      */
     public function emailregisterAction()
     {

core/controllers/components/ApihelperComponent.php

@@ -393,7 +393,8 @@ public function listResourcePermissions($policyStatus, $userPolicies, $groupPoli
      *
      * @param id the group to add the user to
      * @param user_id the user to add to the group
-     * @return an array of (groupModel, groupDao, groupUserDao)
+     * @return array an array of (groupModel, groupDao, groupUserDao)
+     * @throws Exception
      */
     public function validateGroupUserChangeParams($args)
     {
@@ -417,7 +418,7 @@ public function validateGroupUserChangeParams($args)
         $communityModel = MidasLoader::loadModel('Community');
         if (!$communityModel->policyCheck($group->getCommunity(), $userDao, MIDAS_POLICY_ADMIN)
         ) {
-            throw new Zend_Exception("Community Admin permissions required.", MIDAS_INVALID_POLICY);
+            throw new Exception("Community Admin permissions required.", MIDAS_INVALID_POLICY);
         }
 
         $groupUserId = $args['user_id'];
@@ -451,8 +452,9 @@ public function checkMetadataTypeOrName(&$args, &$metadataModel)
      * helper method to validate passed in community privacy status params and
      * map them to valid community privacy codes.
      *
-     * @param  string $privacyStatus , should be 'Private' or 'Public'
-     * @return valid  community privacy code
+     * @param string $privacyStatus should be 'Private' or 'Public'
+     * @return int valid community privacy code
+     * @throws Exception
      */
     public function getValidCommunityPrivacyCode($privacyStatus)
     {
@@ -472,8 +474,9 @@ public function getValidCommunityPrivacyCode($privacyStatus)
      * helper method to validate passed in community can join status params and
      * map them to valid community can join codes.
      *
-     * @param  string $canjoinStatus , should be 'Everyone' or 'Invitation'
-     * @return valid  community canjoin code
+     * @param string $canjoinStatus should be 'Everyone' or 'Invitation'
+     * @return int valid community canjoin code
+     * @throws Exception
      */
     public function getValidCommunityCanjoinCode($canjoinStatus)
     {

core/models/base/CommunityInvitationModelBase.php

@@ -21,7 +21,7 @@
 /** ItemRevisionModelBase */
 class CommunityInvitationModelBase extends AppModel
 {
-    /** Constructor */
+    /** Constructor. */
     public function __construct()
     {
         parent::__construct();
@@ -57,11 +57,13 @@ public function __construct()
     }
 
     /**
-     * Create an invitation record for the user into the given group
+     * Create an invitation record for the user into the given group.
      *
-     * @param groupDao The group to invite the user to
-     * @param userDao The user performing the invitation (typically the session user)
-     * @param invitedUserDao The user being invited to the group
+     * @param GroupDao $groupDao The group to invite the user to
+     * @param UserDao $userDao The user performing the invitation (typically the session user)
+     * @param UserDao $invitedUserDao The user being invited to the group
+     * @return false|CommunityInvitationDao
+     * @throws Zend_Exception
      */
     public function createInvitation($groupDao, $userDao, $invitedUserDao)
     {
@@ -92,7 +94,14 @@ public function createInvitation($groupDao, $userDao, $invitedUserDao)
         return $invitationDao;
     }
 
-    /** is user invited */
+    /**
+     * Is user invited?
+     *
+     * @param CommunityDao $communityDao
+     * @param UserDao $userDao
+     * @param bool $returnDao
+     * @return bool|CommunityInvitationDao
+     */
     public function isInvited($communityDao, $userDao, $returnDao = false)
     {
         if ($userDao == null) {
@@ -112,11 +121,18 @@ public function isInvited($communityDao, $userDao, $returnDao = false)
         return false;
     }
 
-    /** remove invitation */
+    /**
+     * Remove invitation.
+     *
+     * @param CommunityDao $communityDao
+     * @param UserDao $userDao
+     * @return bool
+     * @throws Zend_Exception
+     */
     public function removeInvitation($communityDao, $userDao)
     {
         if ($userDao == null) {
-            return;
+            return false;
         }
         $invitations = $userDao->getInvitations();
         foreach ($invitations as $invitation) {
@@ -133,6 +149,6 @@ public function removeInvitation($communityDao, $userDao)
             }
         }
 
-        return;
+        return false;
     }
 }

core/models/base/CommunityModelBase.php

@@ -374,8 +374,9 @@ public function countBitstreams($communityDao, $userDao = null)
      * which should be one of MIDAS_COMMUNITY_PUBLIC, MIDAS_COMMUNITY_PRIVATE.
      *
      * @param CommunityDao $communityDao
-     * @param type $privacyCode
-     * @param type $userDao
+     * @param int $privacyCode
+     * @param UserDao $userDao
+     * @throws Zend_Exception
      */
     public function setPrivacy($communityDao, $privacyCode, $userDao)
     {
@@ -384,7 +385,7 @@ public function setPrivacy($communityDao, $privacyCode, $userDao)
         }
         if ($privacyCode === false || ($privacyCode != MIDAS_COMMUNITY_PUBLIC && $privacyCode != MIDAS_COMMUNITY_PRIVATE)
         ) {
-            throw new Exception('invalid value for privacyCode: '.$privacyCode);
+            throw new Zend_Exception('invalid value for privacyCode: '.$privacyCode);
         }
 
         $feedModel = MidasLoader::loadModel('Feed');

core/models/base/ItemModelBase.php

@@ -280,9 +280,10 @@ public function addReadonlyPolicy($itemdao, $folderdao)
      * input userDao parameter (who run this operation) and access policy is based on
      * the input folderDao parameter (destination folder)
      *
-     * @param  ItemDao $itemDao the item to be duplicated
-     * @param  UserDao $userDao the user who run this operation
-     * @param  FolderDao $folderDao destination folder
+     * @param ItemDao $itemDao the item to be duplicated
+     * @param UserDao $userDao the user who run this operation
+     * @param FolderDao $folderDao destination folder
+     * @return ItemDao
      * @throws Zend_Exception on invalid input parameters (itemDao, userDao and folderDao)
      */
     public function duplicateItem($itemDao, $userDao, $folderDao)
@@ -403,9 +404,12 @@ public function incrementDownloadCount($itemdao)
         Zend_Registry::get('notifier')->callback("CALLBACK_CORE_PLUS_ONE_DOWNLOAD", array('item' => $itemdao));
     }
 
-    /** Add a revision to an item
+    /**
+     * Add a revision to an item.
      *
-     * @return void
+     * @param ItemDao $itemdao
+     * @param ItemRevisionDao $revisiondao
+     * @throws Zend_Exception
      */
     public function addRevision($itemdao, $revisiondao)
     {
@@ -435,7 +439,9 @@ public function addRevision($itemdao, $revisiondao)
      * Delete an itemrevision from an item, will reduce all other
      * itemrevision revision numbers appropriately.
      *
-     * @return void
+     * @param ItemDao $itemdao
+     * @param ItemRevisionDao $revisiondao
+     * @throws Zend_Exception
      */
     public function removeRevision($itemdao, $revisiondao)
     {