Add documentation to various DAO classes

Author: Jamie Snape

core/models/AppDao.php

@@ -19,8 +19,9 @@
 =========================================================================*/
 
 /**
- *  GlobalDao
- *  Global dao methods
+ * Generic DAO class.
+ *
+ * @package Core\DAO
  */
 class AppDao extends MIDAS_GlobalDao
 {

core/models/GlobalDao.php

@@ -19,15 +19,16 @@
 =========================================================================*/
 
 /**
- *  Global dao methods
+ * Generic DAO base class.
+ *
+ * @package Core\DAO
  */
 class MIDAS_GlobalDao
 {
+    /** @var string */
     protected $key;
 
-    /**
-     * Construct dao
-     */
+    /** Constructor */
     public function __construct()
     {
         if ($this->getModel()->getKey() !== '') {
@@ -39,9 +40,7 @@ public function __construct()
         $this->loadElements();
     }
 
-    /**
-     * Loads model and components
-     */
+    /** Load the components. */
     public function loadElements()
     {
         Zend_Registry::set('components', array());
@@ -58,9 +57,11 @@ public function loadElements()
     }
 
     /**
-     * Init the dao based on the primary key
+     * Initialize the DAO from the primary key.
      *
-     * @param $key Primary Key
+     * @param string $key primary key with which to initialize the DAO
+     * @return bool true if the DAO is successfully initialized
+     * @throws Zend_Exception
      */
     public function initValues($key)
     {
@@ -82,7 +83,11 @@ public function initValues($key)
         return true;
     }
 
-    /** return values as an array */
+    /**
+     * Return the names and values of the fields of the DAO as an associative array.
+     *
+     * @return array
+     */
     public function toArray()
     {
         $return = array();
@@ -99,9 +104,10 @@ public function toArray()
     }
 
     /**
-     * Return key value
+     * Return the value of the key field of the DAO.
      *
-     * @return key
+     * @return mixed
+     * @throws Zend_Exception
      */
     public function getKey()
     {
@@ -114,10 +120,11 @@ public function getKey()
     }
 
     /**
-     * Generic get function. You can define custom function.
+     * Return the value of a field of the DAO.
      *
-     * @param $var name of the element we want to get
-     * @return value
+     * @param string $var name of the field of which to return the value
+     * @return mixed
+     * @throws Zend_Exception
      */
     public function get($var)
     {
@@ -144,10 +151,12 @@ public function get($var)
     }
 
     /**
-     * Set a value
+     * Set the value of a field of the DAO.
      *
-     * @param $var name of the element we want to set
-     * @param $value
+     * @param string $var name of the field of which to set the value
+     * @param mixed $value value of the field
+     * @return void|mixed
+     * @throws Zend_Exception
      */
     public function set($var, $value)
     {
@@ -164,9 +173,10 @@ public function set($var, $value)
     }
 
     /**
-     * Get Model
+     * Return a model.
      *
-     * @return model
+     * @param string|null $name name of the model
+     * @return object
      */
     public function getModel($name = null)
     {
@@ -185,7 +195,7 @@ public function getModel($name = null)
     }
 
     /**
-     * Get Logger
+     * Fetch the logger from the Zend registry.
      *
      * @return Zend_Log
      */
@@ -195,11 +205,12 @@ public function getLogger()
     }
 
     /**
-     * Catch if the method does not exist and create a method dynamically
+     * Invoke inaccessible methods.
      *
-     * @param $method method name
-     * @param $params array of param
-     * @return return the result of the function dynamically created
+     * @param string $method name of the method
+     * @param array $params parameters of the method
+     * @return mixed
+     * @throws Zend_Exception
      */
     public function __call($method, $params)
     {
@@ -233,8 +244,10 @@ public function __call($method, $params)
     }
 
     /**
-     * @param $var name
-     * @return real var
+     * Return a method name given the name of an item of data in a model.
+     *
+     * @param string $var name of an item of data
+     * @return string
      */
     private function _getRealName($var)
     {

core/models/dao/ActivedownloadDao.php

@@ -19,8 +19,20 @@
 =========================================================================*/
 
 /**
+ * Active download lock DAO.
+ *
+ * @method int getActivedownloadId()
+ * @method void setActivedownloadId(int $activeDownloadId)
+ * @method string getIp()
+ * @method void setIp(string $ip)
+ * @method string getDateCreation()
+ * @method void setDateCreation(string $dateCreation)
+ * @method string getLastUpdate()
+ * @method void setLastUpdate(string $lastUpdate)
+ * @package Core\DAO
  */
 class ActivedownloadDao extends AppDao
 {
+    /** @var string */
     public $_model = 'Activedownload';
 }

core/models/dao/AssetstoreDao.php

@@ -19,9 +19,22 @@
 =========================================================================*/
 
 /**
- * DAO Assetstore (table assetstore)
+ * Asset store DAO.
+ *
+ * @method int getAssetstoreId()
+ * @method void setAssetstoreId(int $assetStoreId)
+ * @method string getName()
+ * @method void setName(string $name)
+ * @method string getPath()
+ * @method void setPath(string $path)
+ * @method int getType()
+ * @method void setType(int $type)
+ * @method array getBitstreams()
+ * @method void setBitstreams(array $bitstreams)
+ * @package Core\DAO
  */
 class AssetstoreDao extends AppDao
 {
+    /** @var string */
     public $_model = 'Assetstore';
 }

core/models/dao/BitstreamDao.php

@@ -19,16 +19,46 @@
 =========================================================================*/
 
 /**
- * DAO Bitstream (table bitstream)
+ * Bitstream DAO.
+ *
+ * @method int getBitstreamId()
+ * @method void setBitstreamId(int $bitstreamId)
+ * @method int getItemrevisionId()
+ * @method void setItemrevisionId(int $itemRevisionId)
+ * @method int getAssetstoreId()
+ * @method void setAssetstoreId(int $assetStoreId)
+ * @method string getName()
+ * @method void setName(string $name)
+ * @method string getMimetype()
+ * @method void setMimetype(string $mimeType)
+ * @method int getSizebytes()
+ * @method void setSizebytes(int $sizeBytes)
+ * @method string getChecksum()
+ * @method void setChecksum(string $checksum)
+ * @method string getPath()
+ * @method void setPath(string $path)
+ * @method string getDate()
+ * @method void setDate(string $date)
+ * @method ItemrevisionDao getItemrevision()
+ * @method void setItemrevision(ItemrevisionDao $itemRevision)
+ * @method AssetstoreDao getAssetstore()
+ * @method void setAssetstore(AssetstoreDao $assetStore)
+ * @package Core\DAO
  */
 class BitstreamDao extends AppDao
 {
+    /** @var string */
     public $_model = 'Bitstream';
+
+    /** @var array */
     public $_components = array('MimeType', 'Utility');
 
     /**
-     * Fill the properties of the bitstream given the path.
-     * The file should be accessible from the web server.
+     * Fill in the properties of this bitstream given its path. The file must
+     * accessible by the web server.
+     *
+     * @deprecated
+     * @throws Zend_Exception
      */
     public function fillPropertiesFromPath()
     {
@@ -37,7 +67,7 @@ public function fillPropertiesFromPath()
             throw new Zend_Exception('BitstreamDao path is not set in fillPropertiesFromPath()');
         }
 
-        // TODO Compute the full path from the assetstore. For now using the path
+        // TODO: Compute the full path from the asset store. For now using the path.
         $this->setMimetype($this->Component->MimeType->getType($this->path));
         // clear the stat cache, as the underlying file might have changed
         // since the last time filesize was called on the same filepath
@@ -48,7 +78,13 @@ public function fillPropertiesFromPath()
         }
     }
 
-    /** Returns the full path of the bitstream based on the assetstore and the path of the bitstream */
+    /**
+     * Return the full path of this bitstream from its asset store and the
+     * relative path of the bitstream.
+     *
+     * @deprecated
+     * @return string
+     */
     public function getFullPath()
     {
         $assetstore = $this->get('assetstore');

core/models/dao/CommunityDao.php

@@ -19,9 +19,50 @@
 =========================================================================*/
 
 /**
- * DAO Item (table item)
+ * Community DAO.
+ *
+ * @method int getCommunityId()
+ * @method void setCommunityId(int $communityId)
+ * @method string getName()
+ * @method void setName(string $name)
+ * @method string getDescription()
+ * @method void setDescription(string $description)
+ * @method string getCreation()
+ * @method void setCreation(string $creation)
+ * @method int getPrivacy()
+ * @method void setPrivacy(int $privacy)
+ * @method int getFolderId()
+ * @method void setFolderId(int $folderId)
+ * @method int getAdmingroupId()
+ * @method void setAdmingroupId(int $adminGroupId)
+ * @method int getModeratorgroupId()
+ * @method void setModeratorgroupId(int $moderatorGroupId)
+ * @method int getMembergroupId()
+ * @method void setMembergroupId(int $memberGroupId)
+ * @method int getCanJoin()
+ * @method void setCanJoin(int $canJoin)
+ * @method int getView()
+ * @method void setView(int $view)
+ * @method string getUuid()
+ * @method void setUuid(string $uuid)
+ * @method FolderDao getFolder()
+ * @method void setFolder(FolderDao $folder)
+ * @method GroupDao getAdminGroup()
+ * @method void setAdminGroup(GroupDao $adminGroup)
+ * @method GroupDao getModeratorGroup()
+ * @method void setModeratorGroup(GroupDao $moderatorGroup)
+ * @method array getInvitations()
+ * @method void setInvitations(array $invitations)
+ * @method array getGroups()
+ * @method void setGroups(array $groups)
+ * @method GroupDao getMemberGroup()
+ * @method void setMemberGroup(GroupDao $memberGroup)
+ * @method array getFeeds()
+ * @method void setFeeds(array $feeds)
+ * @package Core\DAO
  */
 class CommunityDao extends AppDao
 {
+    /** @var string */
     public $_model = 'Community';
 }

core/models/dao/CommunityInvitationDao.php

@@ -19,9 +19,26 @@
 =========================================================================*/
 
 /**
- * DAO Assetstore
+ * Community invitation DAO.
+ *
+ * @method int getCommunityinvitationId()
+ * @method void setCommunityinvitationId(int $communityInvitationId)
+ * @method int getCommunityId()
+ * @method void setCommunityId(int $communityId)
+ * @method int getGroupId()
+ * @method void setGroupId(int $groupId)
+ * @method int getUserId()
+ * @method void setUserId(int $userId)
+ * @method CommunityDao getCommunity()
+ * @method void setCommunity(CommunityDao $community)
+ * @method GroupDao getGroup()
+ * @method void setGroup(GroupDao $group)
+ * @method UserDao getUser()
+ * @method void setUser(UserDao $user)
+ * @package Core\DAO
  */
 class CommunityInvitationDao extends AppDao
 {
+    /** @var string */
     public $_model = 'CommunityInvitation';
 }

core/models/dao/ErrorlogDao.php

@@ -19,8 +19,22 @@
 =========================================================================*/
 
 /**
+ * Error log DAO.
+ *
+ * @method int getErrorlogId()
+ * @method void setErrorlogId(int $errorLogId)
+ * @method string getModule()
+ * @method void setModule(string $module)
+ * @method string getMessage()
+ * @method void setMessage(string $message)
+ * @method string getDatetime()
+ * @method void setDatetime(string $dateTime)
+ * @method int getPriority()
+ * @method void setPriority(int $priority)
+ * @package Core\DAO
  */
 class ErrorlogDao extends AppDao
 {
+    /** @var string */
     public $_model = 'Errorlog';
 }