1 files changed, 127 insertions, 56 deletions

diff --git a/modules/forum/forum.module b/modules/forum/forum.module
index eddac7978..7e8d81bde 100644
--- a/modules/forum/forum.module
+++ b/modules/forum/forum.module
@@ -233,7 +233,7 @@ function forum_entity_info_alter(&$info) {
 }
 
 /**
- * Entity URI callback.
+ * Entity URI callback used in forum_entity_info_alter().
  */
 function forum_uri($forum) {
   return array(
@@ -242,7 +242,7 @@ function forum_uri($forum) {
 }
 
 /**
- * Check whether a content type can be used in a forum.
+ * Checks whether a node can be used in a forum, based on its content type.
  *
  * @param $node
  *   A node object.
@@ -283,7 +283,8 @@ function forum_node_view($node, $view_mode) {
 /**
  * Implements hook_node_validate().
  *
- * Check in particular that only a "leaf" term in the associated taxonomy.
+ * Checks in particular that the node is assigned only a "leaf" term in the
+ * forum taxonomy.
  */
 function forum_node_validate($node, $form) {
   if (_forum_node_check_node_type($node)) {
@@ -319,7 +320,7 @@ function forum_node_validate($node, $form) {
 /**
  * Implements hook_node_presave().
  *
- * Assign forum taxonomy when adding a topic from within a forum.
+ * Assigns the forum taxonomy when adding a topic from within a forum.
  */
 function forum_node_presave($node) {
   if (_forum_node_check_node_type($node)) {
@@ -481,7 +482,7 @@ function forum_taxonomy_term_delete($term) {
 /**
  * Implements hook_comment_publish().
  *
- * This actually handles the insert and update of published nodes since
+ * This actually handles the insertion and update of published nodes since
  * comment_save() calls hook_comment_publish() for all published comments.
  */
 function forum_comment_publish($comment) {
@@ -491,12 +492,12 @@ function forum_comment_publish($comment) {
 /**
  * Implements hook_comment_update().
  *
- * Comment module doesn't call hook_comment_unpublish() when saving individual
- * comments so we need to check for those here.
+ * The Comment module doesn't call hook_comment_unpublish() when saving
+ * individual comments, so we need to check for those here.
  */
 function forum_comment_update($comment) {
-  // comment_save() calls hook_comment_publish() for all published comments
-  // so we to handle all other values here.
+  // comment_save() calls hook_comment_publish() for all published comments,
+  // so we need to handle all other values here.
   if (!$comment->status) {
     _forum_update_forum_index($comment->nid);
   }
@@ -669,8 +670,8 @@ function forum_block_save($delta = '', $edit = array()) {
 /**
  * Implements hook_block_view().
  *
- * Generates a block containing the currently active forum topics and the
- * most recently added forum topics.
+ * Generates a block containing the currently active forum topics and the most
+ * recently added forum topics.
  */
 function forum_block_view($delta = '') {
   $query = db_select('forum_index', 'f')
@@ -700,13 +701,12 @@ function forum_block_view($delta = '') {
 }
 
 /**
-* A #pre_render callback. Lists nodes based on the element's #query property.
-*
-* @see forum_block_view()
-*
-* @return
-*   A renderable array.
-*/
+ * Render API callback: Lists nodes based on the element's #query property.
+ *
+ * This function can be used as a #pre_render callback.
+ *
+ * @see forum_block_view()
+ */
 function forum_block_view_pre_render($elements) {
   $result = $elements['#query']->execute();
   if ($node_title_list = node_title_list($result)) {
@@ -730,7 +730,7 @@ function forum_form($node, $form_state) {
 
   if (!empty($node->nid)) {
     $forum_terms = $node->taxonomy_forums;
-    // If editing, give option to leave shadows
+    // If editing, give option to leave shadows.
     $shadow = (count($forum_terms) > 1);
     $form['shadow'] = array('#type' => 'checkbox', '#title' => t('Leave shadow copy'), '#default_value' => $shadow, '#description' => t('If you move this topic, you can leave a link in the old forum to the new forum.'));
     $form['forum_tid'] = array('#type' => 'value', '#value' => $node->forum_tid);
@@ -743,13 +743,15 @@ function forum_form($node, $form_state) {
  * Returns a tree of all forums for a given taxonomy term ID.
  *
  * @param $tid
- *    (optional) Taxonomy ID of the forum, if not givin all forums will be returned.
+ *   (optional) Taxonomy term ID of the forum. If not given all forums will be
+ *   returned.
+ *
  * @return
  *   A tree of taxonomy objects, with the following additional properties:
- *    - 'num_topics': Number of topics in the forum
- *    - 'num_posts': Total number of posts in all topics
- *    - 'last_post': Most recent post for the forum
- *    - 'forums': An array of child forums
+ *   - num_topics: Number of topics in the forum.
+ *   - num_posts: Total number of posts in all topics.
+ *   - last_post: Most recent post for the forum.
+ *   - forums: An array of child forums.
  */
 function forum_forum_load($tid = NULL) {
   $cache = &drupal_static(__FUNCTION__, array());
@@ -857,8 +859,17 @@ function forum_forum_load($tid = NULL) {
 }
 
 /**
- * Calculate the number of nodes the user has not yet read and are newer
- * than NODE_NEW_LIMIT.
+ * Calculates the number of new posts in a forum that the user has not yet read.
+ *
+ * Nodes are new if they are newer than NODE_NEW_LIMIT.
+ *
+ * @param $term
+ *   The term ID of the forum.
+ * @param $uid
+ *   The user ID.
+ *
+ * @return
+ *   The number of new posts in the forum that have not been read by the user.
  */
 function _forum_topics_unread($term, $uid) {
   $query = db_select('node', 'n');
@@ -874,6 +885,23 @@ function _forum_topics_unread($term, $uid) {
     ->fetchField();
 }
 
+/**
+ * Gets all the topics in a forum.
+ *
+ * @param $tid
+ *   The term ID of the forum.
+ * @param $sortby
+ *   One of the following integers indicating the sort criteria:
+ *   - 1: Date - newest first.
+ *   - 2: Date - oldest first.
+ *   - 3: Posts with the most comments first.
+ *   - 4: Posts with the least comments first.
+ * @param $forum_per_page
+ *   The maximum number of topics to display per page.
+ *
+ * @return
+ *   A list of all the topics in a forum.
+ */
 function forum_get_topics($tid, $sortby, $forum_per_page) {
   global $user, $forum_topic_list_header;
 
@@ -944,7 +972,8 @@ function forum_get_topics($tid, $sortby, $forum_per_page) {
   $first_new_found = FALSE;
   foreach ($result as $topic) {
     if ($user->uid) {
-      // folder is new if topic is new or there are new comments since last visit
+      // A forum is new if the topic is new, or if there are new comments since
+      // the user's last visit.
       if ($topic->forum_tid != $tid) {
         $topic->new = 0;
       }
@@ -981,15 +1010,22 @@ function forum_get_topics($tid, $sortby, $forum_per_page) {
 }
 
 /**
- * Process variables for forums.tpl.php
+ * Preprocesses variables for forums.tpl.php.
  *
- * The $variables array contains the following arguments:
- * - $forums
- * - $topics
- * - $parents
- * - $tid
- * - $sortby
- * - $forum_per_page
+ * @param $variables
+ *   An array containing the following elements:
+ *   - forums: An array of all forum objects to display for the given taxonomy
+ *     term ID. If tid = 0 then all the top-level forums are displayed.
+ *   - topics: An array of all the topics in the current forum.
+ *   - parents: An array of taxonomy term objects that are ancestors of the
+ *     current term ID.
+ *   - tid: Taxonomy term ID of the current forum.
+ *   - sortby: One of the following integers indicating the sort criteria:
+ *     - 1: Date - newest first.
+ *     - 2: Date - oldest first.
+ *     - 3: Posts with the most comments first.
+ *     - 4: Posts with the least comments first.
+ *   - forum_per_page: The maximum number of topics to display per page.
  *
  * @see forums.tpl.php
  */
@@ -1060,12 +1096,15 @@ function template_preprocess_forums(&$variables) {
 }
 
 /**
- * Process variables to format a forum listing.
+ * Preprocesses variables for forum-list.tpl.php.
  *
- * $variables contains the following information:
- * - $forums
- * - $parents
- * - $tid
+ * @param $variables
+ *   An array containing the following elements:
+ *   - forums: An array of all forum objects to display for the given taxonomy
+ *     term ID. If tid = 0 then all the top-level forums are displayed.
+ *   - parents: An array of taxonomy term objects that are ancestors of the
+ *     current term ID.
+ *   - tid: Taxonomy term ID of the current forum.
  *
  * @see forum-list.tpl.php
  * @see theme_forum_list()
@@ -1106,13 +1145,13 @@ function template_preprocess_forum_list(&$variables) {
 }
 
 /**
- * Preprocess variables to format the topic listing.
+ * Preprocesses variables for forum-topic-list.tpl.php.
  *
- * $variables contains the following data:
- * - $tid
- * - $topics
- * - $sortby
- * - $forum_per_page
+ * @param $variables
+ *   An array containing the following elements:
+ *   - tid: Taxonomy term ID of the current forum.
+ *   - topics: An array of all the topics in the current forum.
+ *   - forum_per_page: The maximum number of topics to display per page.
  *
  * @see forum-topic-list.tpl.php
  * @see theme_forum_topic_list()
@@ -1162,7 +1201,7 @@ function template_preprocess_forum_topic_list(&$variables) {
     }
   }
   else {
-    // Make this safe for the template
+    // Make this safe for the template.
     $variables['topics'] = array();
   }
   // Give meaning to $tid for themers. $tid actually stands for term id.
@@ -1173,14 +1212,16 @@ function template_preprocess_forum_topic_list(&$variables) {
 }
 
 /**
- * Process variables to format the icon for each individual topic.
+ * Preprocesses variables for forum-icon.tpl.php.
  *
- * $variables contains the following data:
- * - $new_posts
- * - $num_posts = 0
- * - $comment_mode = 0
- * - $sticky = 0
- * - $first_new
+ * @param $variables
+ *   An array containing the following elements:
+ *   - new_posts: Indicates whether or not the topic contains new posts.
+ *   - num_posts: The total number of posts in all topics.
+ *   - comment_mode: An integer indicating whether comments are open, closed,
+ *     or hidden.
+ *   - sticky: Indicates whether the topic is sticky.
+ *   - first_new: Indicates whether this is the first topic with new posts.
  *
  * @see forum-icon.tpl.php
  * @see theme_forum_icon()
@@ -1208,9 +1249,14 @@ function template_preprocess_forum_icon(&$variables) {
 }
 
 /**
- * Process variables to format submission info for display in the forum list and topic list.
+ * Preprocesses variables for forum-submitted.tpl.php.
+ *
+ * The submission information will be displayed in the forum list and topic
+ * list.
  *
- * $variables will contain: $topic
+ * @param $variables
+ *   An array containing the following elements:
+ *   - topic: The topic object.
  *
  * @see forum-submitted.tpl.php
  * @see theme_forum_submitted()
@@ -1220,6 +1266,16 @@ function template_preprocess_forum_submitted(&$variables) {
   $variables['time'] = isset($variables['topic']->created) ? format_interval(REQUEST_TIME - $variables['topic']->created) : '';
 }
 
+/**
+ * Gets the last time the user viewed a node.
+ *
+ * @param $nid
+ *   The node ID.
+ *
+ * @return
+ *   The timestamp when the user last viewed this node, if the user has
+ *   previously viewed the node; otherwise NODE_NEW_LIMIT.
+ */
 function _forum_user_last_visit($nid) {
   global $user;
   $history = &drupal_static(__FUNCTION__, array());
@@ -1233,6 +1289,21 @@ function _forum_user_last_visit($nid) {
   return isset($history[$nid]) ? $history[$nid] : NODE_NEW_LIMIT;
 }
 
+/**
+ * Gets topic sorting information based on an integer code.
+ *
+ * @param $sortby
+ *   One of the following integers indicating the sort criteria:
+ *   - 1: Date - newest first.
+ *   - 2: Date - oldest first.
+ *   - 3: Posts with the most comments first.
+ *   - 4: Posts with the least comments first.
+ *
+ * @return
+ *   An array with the following values:
+ *   - field: A field for an SQL query.
+ *   - sort: 'asc' or 'desc'.
+ */
 function _forum_get_topic_order($sortby) {
   switch ($sortby) {
     case 1: