Issue #1315214 by NROTC_Webmaster, kathyh, aenw: Clean up API docs and comments in the Tracker module code

4 files changed, 61 insertions, 28 deletions

diff --git a/modules/tracker/tracker.install b/modules/tracker/tracker.install
index 244f53778..84305d822 100644
--- a/modules/tracker/tracker.install
+++ b/modules/tracker/tracker.install
@@ -1,6 +1,11 @@
 <?php
 
 /**
+ * @file
+ * Install, update, and uninstall functions for tracker.module.
+ */
+
+/**
  * Implements hook_uninstall().
  */
 function tracker_uninstall() {
diff --git a/modules/tracker/tracker.module b/modules/tracker/tracker.module
index 227cf7209..70701d6d4 100644
--- a/modules/tracker/tracker.module
+++ b/modules/tracker/tracker.module
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Enables tracking of recent content for users.
+ * Tracks recent content posted by a user or users.
  */
 
 /**
@@ -70,6 +70,11 @@ function tracker_menu() {
 
 /**
  * Implements hook_cron().
+ *
+ * Updates tracking information for any items still to be tracked. The variable
+ * 'tracker_index_nid' is set to ((the last node ID that was indexed) - 1) and
+ * used to select the nodes to be processed. If there are no remaining nodes to
+ * process, 'tracker_index_nid' will be 0.
  */
 function tracker_cron() {
   $max_nid = variable_get('tracker_index_nid', 0);
@@ -164,6 +169,8 @@ function _tracker_user_access($account) {
 
 /**
  * Implements hook_node_insert().
+ *
+ * Adds new tracking information for this node since it's new.
  */
 function tracker_node_insert($node, $arg = 0) {
   _tracker_add($node->nid, $node->uid, $node->changed);
@@ -171,6 +178,8 @@ function tracker_node_insert($node, $arg = 0) {
 
 /**
  * Implements hook_node_update().
+ *
+ * Adds tracking information for this node since it's been updated.
  */
 function tracker_node_update($node, $arg = 0) {
   _tracker_add($node->nid, $node->uid, $node->changed);
@@ -178,6 +187,8 @@ function tracker_node_update($node, $arg = 0) {
 
 /**
  * Implements hook_node_delete().
+ *
+ * Deletes tracking information for a node.
  */
 function tracker_node_delete($node, $arg = 0) {
   db_delete('tracker_node')
@@ -196,7 +207,7 @@ function tracker_node_delete($node, $arg = 0) {
  */
 function tracker_comment_update($comment) {
   // comment_save() calls hook_comment_publish() for all published comments
-  // so we to handle all other values here.
+  // so we need to handle all other values here.
   if ($comment->status != COMMENT_PUBLISHED) {
     _tracker_remove($comment->nid, $comment->uid, $comment->changed);
   }
@@ -227,7 +238,7 @@ function tracker_comment_delete($comment) {
 }
 
 /**
- * Update indexing tables when a node is added, updated or commented on.
+ * Updates indexing tables when a node is added, updated, or commented on.
  *
  * @param $nid
  *   A node ID.
@@ -266,7 +277,7 @@ function _tracker_add($nid, $uid, $changed) {
 }
 
 /**
- * Determine the max timestamp between $node->changed and the last comment.
+ * Determines the max timestamp between $node->changed and the last comment.
  *
  * @param $nid
  *   A node ID.
@@ -288,7 +299,7 @@ function _tracker_calculate_changed($nid) {
 }
 
 /**
- * Clean up indexed data when nodes or comments are removed.
+ * Cleans up indexed data when nodes or comments are removed.
  *
  * @param $nid
  *  The node ID.
@@ -301,8 +312,8 @@ function _tracker_remove($nid, $uid = NULL, $changed = NULL) {
   $node = db_query('SELECT nid, status, uid, changed FROM {node} WHERE nid = :nid', array(':nid' => $nid))->fetchObject();
 
   // The user only keeps his or her subscription if both of the following are true:
-  // (1) The node exists.
-  // (2) The user is either the node author or has commented on the node.
+  //   (1) The node exists.
+  //   (2) The user is either the node author or has commented on the node.
   $keep_subscription = FALSE;
 
   if ($node) {
@@ -311,7 +322,7 @@ function _tracker_remove($nid, $uid = NULL, $changed = NULL) {
 
     // Comments are a second reason to keep the user's subscription.
     if (!$keep_subscription) {
-      // Check if the user has commented at least once on the given nid
+      // Check if the user has commented at least once on the given nid.
       $keep_subscription = db_query_range('SELECT COUNT(*) FROM {comment} WHERE nid = :nid AND uid = :uid AND status = :status', 0, 1, array(
         ':nid' => $nid,
         ':uid' => $uid,
@@ -329,9 +340,8 @@ function _tracker_remove($nid, $uid = NULL, $changed = NULL) {
 
     // Now we need to update the (possibly) changed timestamps for other users
     // and the node itself.
-
     // We only need to do this if the removed item has a timestamp that equals
-    // or exceeds the listed changed timestamp for the node
+    // or exceeds the listed changed timestamp for the node.
     $tracker_node = db_query('SELECT nid, changed FROM {tracker_node} WHERE nid = :nid', array(':nid' => $nid))->fetchObject();
     if ($tracker_node && $changed >= $tracker_node->changed) {
       // If we're here, the item being removed is *possibly* the item that
@@ -356,7 +366,7 @@ function _tracker_remove($nid, $uid = NULL, $changed = NULL) {
         ))
         ->condition('nid', $nid)
         ->execute();
-   }
+    }
   }
   else {
     // If the node doesn't exist, remove everything.
diff --git a/modules/tracker/tracker.pages.inc b/modules/tracker/tracker.pages.inc
index 7b1e946f3..baa99866c 100644
--- a/modules/tracker/tracker.pages.inc
+++ b/modules/tracker/tracker.pages.inc
@@ -2,12 +2,15 @@
 
 /**
  * @file
- * User page callbacks for the tracker module.
+ * User page callbacks for tracker.module.
  */
 
 
 /**
- * Menu callback; prints a listing of active nodes on the site.
+ * Page callback: prints a listing of active nodes on the site.
+ *
+ * Queries the database for info, adds RDFa info if applicable, and generates
+ * the render array that will be used to render the page.
  */
 function tracker_page($account = NULL, $set_title = FALSE) {
   if ($account) {
@@ -38,23 +41,23 @@ function tracker_page($account = NULL, $set_title = FALSE) {
 
   $rows = array();
   if (!empty($nodes)) {
-    // Now, get the data and put into the placeholder array
+    // Now, get the data and put into the placeholder array.
     $result = db_query('SELECT n.nid, n.title, n.type, n.changed, n.uid, u.name, l.comment_count FROM {node} n INNER JOIN {node_comment_statistics} l ON n.nid = l.nid INNER JOIN {users} u ON n.uid = u.uid WHERE n.nid IN (:nids)', array(':nids' => array_keys($nodes)), array('target' => 'slave'));
     foreach ($result as $node) {
       $node->last_activity = $nodes[$node->nid]->changed;
       $nodes[$node->nid] = $node;
     }
 
-    // Finally display the data
+    // Display the data.
     foreach ($nodes as $node) {
-      // Determine the number of comments:
+      // Determine the number of comments.
       $comments = 0;
       if ($node->comment_count) {
         $comments = $node->comment_count;
 
         if ($new = comment_num_new($node->nid)) {
           $comments .= '<br />';
-          $comments .= l(format_plural($new, '1 new', '@count new'), 'node/'. $node->nid, array('fragment' => 'new'));
+          $comments .= l(format_plural($new, '1 new', '@count new'), 'node/' . $node->nid, array('fragment' => 'new'));
         }
       }
 
@@ -97,7 +100,7 @@ function tracker_page($account = NULL, $set_title = FALSE) {
         $row['last updated'] += $mapping_last_activity;
 
         // We need to add the about attribute on the tr tag to specify which
-        // node the RDFa annoatations above apply to. We move the content of
+        // node the RDFa annotations above apply to. We move the content of
         // $row to a 'data' sub array so we can specify attributes for the row.
         $row = array('data' => $row);
         $row['about'] = url('node/' . $node->nid);
diff --git a/modules/tracker/tracker.test b/modules/tracker/tracker.test
index a559f1b64..d429210d2 100644
--- a/modules/tracker/tracker.test
+++ b/modules/tracker/tracker.test
@@ -5,8 +5,23 @@
  * Tests for tracker.module.
  */
 
+/**
+ * Defines a base class for testing tracker.module.
+ */
 class TrackerTest extends DrupalWebTestCase {
+
+  /**
+   * The main user for testing.
+   *
+   * @var object
+   */
   protected $user;
+
+  /**
+   * A second user that will 'create' comments and nodes.
+   *
+   * @var object
+   */
   protected $other_user;
 
   public static function getInfo() {
@@ -29,13 +44,13 @@ class TrackerTest extends DrupalWebTestCase {
   }
 
   /**
-   * Test the presence of nodes on the global tracker listing.
+   * Tests for the presence of nodes on the global tracker listing.
    */
   function testTrackerAll() {
     $this->drupalLogin($this->user);
 
     $unpublished = $this->drupalCreateNode(array(
-      'title' =>$this->randomName(8),
+      'title' => $this->randomName(8),
       'status' => 0,
     ));
     $published = $this->drupalCreateNode(array(
@@ -55,7 +70,7 @@ class TrackerTest extends DrupalWebTestCase {
   }
 
   /**
-   * Test the presence of nodes on a user's tracker listing.
+   * Tests for the presence of nodes on a user's tracker listing.
    */
   function testTrackerUser() {
     $this->drupalLogin($this->user);
@@ -101,7 +116,7 @@ class TrackerTest extends DrupalWebTestCase {
   }
 
   /**
-   * Test the presence of the "new" flag for nodes.
+   * Tests for the presence of the "new" flag for nodes.
    */
   function testTrackerNewNodes() {
     $this->drupalLogin($this->user);
@@ -129,7 +144,7 @@ class TrackerTest extends DrupalWebTestCase {
   }
 
   /**
-   * Test comment counters on the tracker listing.
+   * Tests for comment counters on the tracker listing.
    */
   function testTrackerNewComments() {
     $this->drupalLogin($this->user);
@@ -144,7 +159,8 @@ class TrackerTest extends DrupalWebTestCase {
       'subject' => $this->randomName(),
       'comment_body[' . LANGUAGE_NONE . '][0][value]' => $this->randomName(20),
     );
-    $this->drupalPost('comment/reply/' . $node->nid, $comment, t('Save')); // The new comment is automatically viewed by the current user.
+    // The new comment is automatically viewed by the current user.
+    $this->drupalPost('comment/reply/' . $node->nid, $comment, t('Save'));
 
     $this->drupalLogin($this->other_user);
     $this->drupalGet('tracker');
@@ -157,7 +173,7 @@ class TrackerTest extends DrupalWebTestCase {
       'comment_body[' . LANGUAGE_NONE . '][0][value]' => $this->randomName(20),
     );
     // If the comment is posted in the same second as the last one then Drupal
-    // can't tell a difference, so wait one second here.
+    // can't tell the difference, so we wait one second here.
     sleep(1);
     $this->drupalPost('comment/reply/' . $node->nid, $comment, t('Save'));
 
@@ -167,7 +183,7 @@ class TrackerTest extends DrupalWebTestCase {
   }
 
   /**
-   * Test that existing nodes are indexed by cron.
+   * Tests that existing nodes are indexed by cron.
    */
   function testTrackerCronIndexing() {
     $this->drupalLogin($this->user);
@@ -213,7 +229,6 @@ class TrackerTest extends DrupalWebTestCase {
     $this->assertText('1 new', t('New comment is counted on the tracker listing pages.'));
     $this->assertText('updated', t('Node is listed as updated'));
 
-
     // Fetch the site-wide tracker.
     $this->drupalGet('tracker');
 
@@ -225,7 +240,7 @@ class TrackerTest extends DrupalWebTestCase {
   }
 
   /**
-   * Test that publish/unpublish works at admin/content/node
+   * Tests that publish/unpublish works at admin/content/node.
    */
   function testTrackerAdminUnpublish() {
     $admin_user = $this->drupalCreateUser(array('access content overview', 'administer nodes', 'bypass node access'));