Add more documentation to tracker module

Author: Jamie Snape

modules/tracker/AppController.php

@@ -18,8 +18,13 @@
  limitations under the License.
 =========================================================================*/
 
-/** App controller for the tracker module */
+/**
+ * Generic controller class for the tracker module.
+ *
+ * @package Modules\Tracker\Controller
+ */
 class Tracker_AppController extends MIDAS_GlobalModule
 {
+    /** @var string */
     public $moduleName = 'tracker';
 }

modules/tracker/Bootstrap.php

@@ -18,7 +18,11 @@
  limitations under the License.
 =========================================================================*/
 
-/** Bootstrap for the tracker module. */
+/**
+ * Bootstrap for the tracker module.
+ *
+ * @package Modules\Tracker\Bootstrap
+ */
 class Tracker_Bootstrap extends Zend_Application_Module_Bootstrap
 {
 }

modules/tracker/Notification.php

@@ -20,15 +20,34 @@
 
 require_once BASE_PATH.'/modules/api/library/APIEnabledNotification.php';
 
-/** Notification manager for the tracker module */
+/**
+ * Notification manager for the tracker module.
+ *
+ * @property Tracker_ScalarModel $Tracker_Scalar
+ * @property Tracker_TrendModel $Tracker_Trend
+ * @package Modules\Tracker\Notification
+ */
 class Tracker_Notification extends ApiEnabled_Notification
 {
+    /** @var string */
     public $moduleName = 'tracker';
+
+    /** @var array */
     public $_models = array('User');
+
+    /** @var array */
     public $_moduleModels = array('Scalar', 'Trend');
+
+    /** @var array */
     public $_moduleComponents = array('Api');
 
-    /** init notification process */
+    /** @var string */
+    public $moduleWebroot = null;
+
+    /** @var string */
+    public $webroot = null;
+
+    /** Initialize the notification process. */
     public function init()
     {
         $baseUrl = Zend_Controller_Front::getInstance()->getBaseUrl();
@@ -51,61 +70,85 @@ public function init()
     }
 
     /**
-     * Show trackers tab on the community view page
+     * Show the trackers tab on the community view page.
+     *
+     * @param array $args associative array of parameters including the key "community"
+     * @return array
      */
     public function communityViewTabs($args)
     {
+        /** @var CommunityDao $community */
         $community = $args['community'];
 
         return array('Trackers' => $this->moduleWebroot.'/producer/list?communityId='.$community->getKey());
     }
 
     /**
-     * When a community is deleted, we must delete all associated producers
+     * When a community is deleted, we must delete all associated producers.
+     *
+     * @todo
+     * @param array $args associative array of parameters including the key "community"
      */
     public function communityDeleted($args)
     {
-        // TODO
-        // $comm = $args['community'];
+        // TODO: Implement communityDeleted().
     }
 
     /**
-     * When an item is deleted, we must delete associated item2scalar records
+     * When an item is deleted, we must delete associated item2scalar records.
+     *
+     * @todo
+     * @param array $args associative array of parameters including the key "item"
      */
     public function itemDeleted($args)
     {
-        // TODO
-        // $item = $args['item'];
+        // TODO: Implement itemDeleted().
     }
 
     /**
-     * When a user is deleted, we should delete their threshold notifications
+     * When a user is deleted, we should delete their threshold notifications.
+     *
+     * @todo
+     * @param array $args associative array of parameters including the key "userDao"
      */
     public function userDeleted($args)
     {
-        // TODO
-        // $user = $args['userDao'];
+        // TODO: Implement userDeleted().
     }
 
     /**
      * Delete temporary (unofficial) scalars after n hours, where n is specified as
-     * a module configuration option
+     * a module configuration option.
+     *
+     * @param array $params associative array of parameters including the key "scalarId"
      */
     public function deleteTempScalar($params)
     {
+        /** @var int $scalarId */
         $scalarId = $params['scalarId'];
+
+        /** @var Tracker_ScalarDao $scalar */
         $scalar = $this->Tracker_Scalar->load($scalarId);
         $this->Tracker_Scalar->delete($scalar);
     }
 
     /**
-     * Send an email to the user that a threshold was crossed
+     * Send an email to the user that a threshold was crossed.
+     *
+     * @param array $params associative array of parameters including the keys "notification" and "scalar"
      */
     public function sendEmail($params)
     {
+        /** @var array $notification */
         $notification = $params['notification'];
+
+        /** @var array $scalar */
         $scalar = $params['scalar'];
+
+        /** @var Tracker_TrendDao $trend */
         $trend = $this->Tracker_Trend->load($scalar['trend_id']);
+
+        /** @var UserDao $user */
         $user = $this->User->load($notification['recipient_id']);
         $producer = $trend->getProducer();
 
@@ -129,7 +172,7 @@ public function sendEmail($params)
             ).'">'.$trend->getDisplayName().'</a><br/>';
         $body .= '<b>Value:</b> '.$scalar['value'];
 
-        $result = Zend_Registry::get('notifier')->callback(
+        Zend_Registry::get('notifier')->callback(
             'CALLBACK_CORE_SEND_MAIL_MESSAGE',
             array(
                 'to' => $email,

modules/tracker/controllers/AdminController.php

@@ -18,7 +18,11 @@
  limitations under the License.
 =========================================================================*/
 
-/** Admin controller for the tracker module. */
+/**
+ * Admin controller for the tracker module.
+ *
+ * @package Modules\Tracker\Controller
+ */
 class Tracker_AdminController extends Tracker_AppController
 {
     /** @var array */
@@ -32,8 +36,11 @@ public function indexAction()
         $this->view->pageTitle = 'Tracker Module Configuration';
         $form = new Tracker_Form_Admin();
 
-        if ($this->getRequest()->isPost()) {
-            $data = $this->getRequest()->getPost();
+        /** @var Zend_Controller_Request_Http $request */
+        $request = $this->getRequest();
+
+        if ($request->isPost()) {
+            $data = $request->getPost();
 
             if ($form->isValid($data)) {
                 $values = $form->getValues();
@@ -49,6 +56,7 @@ public function indexAction()
         } else {
             $elements = $form->getElements();
 
+            /** @var Zend_Form_Element $element */
             foreach ($elements as $element) {
                 $name = $element->getName();
 

modules/tracker/controllers/ProducerController.php

@@ -18,26 +18,43 @@
  limitations under the License.
 =========================================================================*/
 
-/** Producer controller */
+/**
+ * Producer controller for the tracker module.
+ *
+ * @property Tracker_ProducerModel $Tracker_Producer
+ * @property Tracker_TrendModel $Tracker_Trend
+ * @package Modules\Tracker\Controller
+ */
 class Tracker_ProducerController extends Tracker_AppController
 {
+    /** @var array */
     public $_components = array('Breadcrumb');
+
+    /** @var array */
     public $_models = array('Community');
+
+    /** @var array */
     public $_moduleModels = array('Producer', 'Trend');
 
     /**
      * List all producers for a given community (in the tab). Requires read permission on community.
      *
-     * @param communityId The community id
+     * Request parameters:
+     *     communityId - The community id
+     *
      * @throws Zend_Exception
      */
     public function listAction()
     {
         $this->disableLayout();
+
+        /** @var int $commId */
         $commId = $this->getParam('communityId');
         if (!isset($commId)) {
             throw new Zend_Exception('Must pass communityId parameter');
         }
+
+        /** @var CommunityDao $comm */
         $comm = $this->Community->load($commId);
         if (!$comm || !$this->Community->policyCheck($comm, $this->userSession->Dao, MIDAS_POLICY_READ)
         ) {
@@ -48,17 +65,22 @@ public function listAction()
     }
 
     /**
-     * View a producer, displaying all available trends
+     * View a producer, displaying all available trends.
+     *
+     * Request parameters:
+     *     producerId - The id of the producer to display (requires community read permission)
      *
-     * @param producerId The id of the producer to display (requires community read permission)
      * @throws Zend_Exception
      */
     public function viewAction()
     {
+        /** @var int $producerId */
         $producerId = $this->getParam('producerId');
         if (!isset($producerId)) {
             throw new Zend_Exception('Must pass producerId parameter');
         }
+
+        /** @var Tracker_ProducerDao $producer */
         $producer = $this->Tracker_Producer->load($producerId);
         $comm = $producer->getCommunity();
         if (!$producer || !$this->Community->policyCheck($comm, $this->userSession->Dao, MIDAS_POLICY_READ)
@@ -80,19 +102,25 @@ public function viewAction()
     }
 
     /**
-     * Delete a producer, deleting all trend data within it (requires community admin)
+     * Delete a producer, deleting all trend data within it (requires community admin).
+     *
+     * Request parameters:
+     *     producerId - The id of the producer to delete
      *
-     * @param producerId The id of the producer to delete
      * @throws Zend_Exception
      */
     public function deleteAction()
     {
         $this->disableLayout();
         $this->disableView();
+
+        /** @var int $producerId */
         $producerId = $this->getParam('producerId');
         if (!isset($producerId)) {
             throw new Zend_Exception('Must pass producerId parameter');
         }
+
+        /** @var Tracker_ProducerDao $producer */
         $producer = $this->Tracker_Producer->load($producerId);
         $comm = $producer->getCommunity();
         if (!$producer || !$this->Community->policyCheck($comm, $this->userSession->Dao, MIDAS_POLICY_ADMIN)
@@ -103,17 +131,20 @@ public function deleteAction()
     }
 
     /**
-     * Show the dialog for editing the producer information
+     * Show the dialog for editing the producer information.
      *
      * @throws Zend_Exception
      */
     public function editAction()
     {
+        /** @var int $producerId */
         $producerId = $this->getParam('producerId');
 
         if (!isset($producerId)) {
             throw new Zend_Exception('Must pass producerId parameter');
         }
+
+        /** @var Tracker_ProducerDao $producer */
         $producer = $this->Tracker_Producer->load($producerId);
         if (!$producer) {
             throw new Zend_Exception('Invalid producerId', 404);
@@ -127,20 +158,26 @@ public function editAction()
     }
 
     /**
-     * Handle edit form submission
+     * Handle edit form submission.
+     *
+     * Request parameters:
+     *     producerId - The id of the producer to edit
      *
-     * @param producerId The id of the producer to edit
      * @throws Zend_Exception
      */
     public function editsubmitAction()
     {
         $this->disableLayout();
         $this->disableView();
+
+        /** @var int $producerId */
         $producerId = $this->getParam('producerId');
 
         if (!isset($producerId)) {
             throw new Zend_Exception('Must pass producerId parameter');
         }
+
+        /** @var Tracker_ProducerDao $producer */
         $producer = $this->Tracker_Producer->load($producerId);
         if (!$this->Community->policyCheck($producer->getCommunity(), $this->userSession->Dao, MIDAS_POLICY_ADMIN)
         ) {