Issue #1357138 by tim.plunkett, jstoller, xenophyle: Fix up API docs for Forum module

12 files changed, 339 insertions, 160 deletions

diff --git a/modules/forum/forum-icon.tpl.php b/modules/forum/forum-icon.tpl.php
index 9cf2cd8d3..fd1cd1308 100644
--- a/modules/forum/forum-icon.tpl.php
+++ b/modules/forum/forum-icon.tpl.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Default theme implementation to display an appropriate icon for a forum post.
+ * Displays an appropriate icon for a forum post.
  *
  * Available variables:
  * - $new_posts: Indicates whether or not the topic contains new posts.
@@ -12,6 +12,8 @@
  *
  * @see template_preprocess_forum_icon()
  * @see theme_forum_icon()
+ *
+ * @ingroup themeable
  */
 ?>
 <div class="topic-status-<?php print $icon_class ?>" title="<?php print $icon_title ?>">
diff --git a/modules/forum/forum-list.tpl.php b/modules/forum/forum-list.tpl.php
index 257cea947..01c74a34c 100644
--- a/modules/forum/forum-list.tpl.php
+++ b/modules/forum/forum-list.tpl.php
@@ -2,34 +2,35 @@
 
 /**
  * @file
- * Default theme implementation to display a list of forums and containers.
+ * Displays a list of forums and containers.
  *
  * Available variables:
  * - $forums: An array of forums and containers to display. It is keyed to the
- *   numeric id's of all child forums and containers.
- * - $forum_id: Forum id for the current forum. Parent to all items within
- *   the $forums array.
- *
- * Each $forum in $forums contains:
- * - $forum->is_container: Is TRUE if the forum can contain other forums. Is
- *   FALSE if the forum can contain only topics.
- * - $forum->depth: How deep the forum is in the current hierarchy.
- * - $forum->zebra: 'even' or 'odd' string used for row class.
- * - $forum->icon_class: 'default' or 'new' string used for forum icon class.
- * - $forum->icon_title: Text alternative for the forum icon.
- * - $forum->name: The name of the forum.
- * - $forum->link: The URL to link to this forum.
- * - $forum->description: The description of this forum.
- * - $forum->new_topics: True if the forum contains unread posts.
- * - $forum->new_url: A URL to the forum's unread posts.
- * - $forum->new_text: Text for the above URL which tells how many new posts.
- * - $forum->old_topics: A count of posts that have already been read.
- * - $forum->num_posts: The total number of posts in the forum.
- * - $forum->last_reply: Text representing the last time a forum was posted or
- *   commented in.
+ *   numeric IDs of all child forums and containers. Each $forum in $forums
+ *   contains:
+ *   - $forum->is_container: TRUE if the forum can contain other forums. FALSE
+ *     if the forum can contain only topics.
+ *   - $forum->depth: How deep the forum is in the current hierarchy.
+ *   - $forum->zebra: 'even' or 'odd' string used for row class.
+ *   - $forum->icon_class: 'default' or 'new' string used for forum icon class.
+ *   - $forum->icon_title: Text alternative for the forum icon.
+ *   - $forum->name: The name of the forum.
+ *   - $forum->link: The URL to link to this forum.
+ *   - $forum->description: The description of this forum.
+ *   - $forum->new_topics: TRUE if the forum contains unread posts.
+ *   - $forum->new_url: A URL to the forum's unread posts.
+ *   - $forum->new_text: Text for the above URL, which tells how many new posts.
+ *   - $forum->old_topics: A count of posts that have already been read.
+ *   - $forum->num_posts: The total number of posts in the forum.
+ *   - $forum->last_reply: Text representing the last time a forum was posted or
+ *     commented in.
+ * - $forum_id: Forum ID for the current forum. Parent to all items within the
+ *   $forums array.
  *
  * @see template_preprocess_forum_list()
  * @see theme_forum_list()
+ *
+ * @ingroup themeable
  */
 ?>
 <table id="forum-<?php print $forum_id; ?>">
diff --git a/modules/forum/forum-rtl.css b/modules/forum/forum-rtl.css
index 81dd4d396..b475e4286 100644
--- a/modules/forum/forum-rtl.css
+++ b/modules/forum/forum-rtl.css
@@ -1,3 +1,7 @@
+/**
+ * @file
+ * Right-to-left styling for the Forum module.
+ */
 
 #forum td.forum .icon {
   float: right;
diff --git a/modules/forum/forum-submitted.tpl.php b/modules/forum/forum-submitted.tpl.php
index d310448c7..18fea8f1b 100644
--- a/modules/forum/forum-submitted.tpl.php
+++ b/modules/forum/forum-submitted.tpl.php
@@ -2,18 +2,20 @@
 
 /**
  * @file
- * Default theme implementation to format a simple string indicated when and
- * by whom a topic was submitted.
+ * Formats a forum post submission string.
  *
- * Available variables:
+ * The submission string indicates when and by whom a topic was submitted.
  *
+ * Available variables:
  * - $author: The author of the post.
  * - $time: How long ago the post was created.
- * - $topic: An object with the raw data of the post. Unsafe, be sure
- *   to clean this data before printing.
+ * - $topic: An object with the raw data of the post. Potentially unsafe. Be
+ *   sure to clean this data before printing.
  *
  * @see template_preprocess_forum_submitted()
  * @see theme_forum_submitted()
+ *
+ * @ingroup themeable
  */
 ?>
 <?php if ($time): ?>
diff --git a/modules/forum/forum-topic-list.tpl.php b/modules/forum/forum-topic-list.tpl.php
index 33907036f..64278141e 100644
--- a/modules/forum/forum-topic-list.tpl.php
+++ b/modules/forum/forum-topic-list.tpl.php
@@ -2,35 +2,39 @@
 
 /**
  * @file
- * Default theme implementation to display a list of forum topics.
+ * Displays a list of forum topics.
  *
  * Available variables:
  * - $header: The table header. This is pre-generated with click-sorting
  *   information. If you need to change this, see
  *   template_preprocess_forum_topic_list().
  * - $pager: The pager to display beneath the table.
- * - $topics: An array of topics to be displayed.
- * - $topic_id: Numeric id for the current forum topic.
- *
- * Each $topic in $topics contains:
- * - $topic->icon: The icon to display.
- * - $topic->moved: A flag to indicate whether the topic has been moved to
- *   another forum.
- * - $topic->title: The title of the topic. Safe to output.
- * - $topic->message: If the topic has been moved, this contains an
- *   explanation and a link.
- * - $topic->zebra: 'even' or 'odd' string used for row class.
- * - $topic->comment_count: The number of replies on this topic.
- * - $topic->new_replies: A flag to indicate whether there are unread comments.
- * - $topic->new_url: If there are unread replies, this is a link to them.
- * - $topic->new_text: Text containing the translated, properly pluralized count.
- * - $topic->created: An outputtable string represented when the topic was posted.
- * - $topic->last_reply: An outputtable string representing when the topic was
- *   last replied to.
- * - $topic->timestamp: The raw timestamp this topic was posted.
+ * - $topics: An array of topics to be displayed. Each $topic in $topics
+ *   contains:
+ *   - $topic->icon: The icon to display.
+ *   - $topic->moved: A flag to indicate whether the topic has been moved to
+ *     another forum.
+ *   - $topic->title: The title of the topic. Safe to output.
+ *   - $topic->message: If the topic has been moved, this contains an
+ *     explanation and a link.
+ *   - $topic->zebra: 'even' or 'odd' string used for row class.
+ *   - $topic->comment_count: The number of replies on this topic.
+ *   - $topic->new_replies: A flag to indicate whether there are unread
+ *     comments.
+ *   - $topic->new_url: If there are unread replies, this is a link to them.
+ *   - $topic->new_text: Text containing the translated, properly pluralized
+ *     count.
+ *   - $topic->created: A string representing when the topic was posted. Safe
+ *     to output.
+ *   - $topic->last_reply: An outputtable string representing when the topic was
+ *     last replied to.
+ *   - $topic->timestamp: The raw timestamp this topic was posted.
+ * - $topic_id: Numeric ID for the current forum topic.
  *
  * @see template_preprocess_forum_topic_list()
  * @see theme_forum_topic_list()
+ *
+ * @ingroup themeable
  */
 ?>
 <table id="forum-topic-<?php print $topic_id; ?>">
diff --git a/modules/forum/forum.admin.inc b/modules/forum/forum.admin.inc
index 49c71d90a..712cf546e 100644
--- a/modules/forum/forum.admin.inc
+++ b/modules/forum/forum.admin.inc
@@ -2,7 +2,22 @@
 
 /**
  * @file
- * Administrative page callbacks for the forum module.
+ * Administrative page callbacks for the Forum module.
+ */
+
+/**
+ * Page callback: Returns a form for creating a new forum or container.
+ *
+ * @param $type
+ *   What is being added. Possible values are 'forum' and 'container'.
+ * @param $edit
+ *   (optional) Associative array containing a forum term to be edited.
+ *   Defaults to an empty array.
+ *
+ * @return
+ *   A form for creating a new forum or container.
+ *
+ * @see forum_menu()
  */
 function forum_form_main($type, $edit = array()) {
   $edit = (array) $edit;
@@ -20,11 +35,14 @@ function forum_form_main($type, $edit = array()) {
 }
 
 /**
- * Returns a form for adding a forum to the forum vocabulary
+ * Form constructor for adding and editing a forum.
+ *
+ * @param $edit
+ *   (optional) Associative array containing a forum term to be added or edited.
+ *   Defaults to an empty array.
  *
- * @param $edit Associative array containing a forum term to be added or edited.
- * @ingroup forms
  * @see forum_form_submit()
+ * @ingroup forms
  */
 function forum_form_forum($form, &$form_state, $edit = array()) {
   $edit += array(
@@ -67,7 +85,7 @@ function forum_form_forum($form, &$form_state, $edit = array()) {
 }
 
 /**
- * Process forum form and container form submissions.
+ * Form submission handler for forum_form_forum() and forum_form_container().
  */
 function forum_form_submit($form, &$form_state) {
   if ($form['form_id']['#value'] == 'forum_form_container') {
@@ -104,8 +122,8 @@ function forum_form_submit($form, &$form_state) {
 /**
  * Returns HTML for a forum form.
  *
- * By default this does not alter the appearance of a form at all,
- * but is provided as a convenience for themers.
+ * By default this does not alter the appearance of a form at all, but is
+ * provided as a convenience for themers.
  *
  * @param $variables
  *   An associative array containing:
@@ -118,11 +136,14 @@ function theme_forum_form($variables) {
 }
 
 /**
- * Returns a form for adding a container to the forum vocabulary
+ * Form constructor for adding and editing forum containers.
+ *
+ * @param $edit
+ *   (optional) Associative array containing a container term to be added or edited.
+ *   Defaults to an empty array.
  *
- * @param $edit Associative array containing a container term to be added or edited.
- * @ingroup forms
  * @see forum_form_submit()
+ * @ingroup forms
  */
 function forum_form_container($form, &$form_state, $edit = array()) {
   $edit += array(
@@ -176,9 +197,13 @@ function forum_form_container($form, &$form_state, $edit = array()) {
 }
 
 /**
- * Returns a confirmation page for deleting a forum taxonomy term.
+ * Form constructor for confirming deletion of a forum taxonomy term.
+ *
+ * @param $tid
+ *   ID of the term to be deleted.
  *
- * @param $tid ID of the term to be deleted
+ * @see forum_confirm_delete_submit()
+ * @ingroup forms
  */
 function forum_confirm_delete($form, &$form_state, $tid) {
   $term = taxonomy_term_load($tid);
@@ -190,7 +215,7 @@ function forum_confirm_delete($form, &$form_state, $tid) {
 }
 
 /**
- * Implement forms api _submit call. Deletes a forum after confirmation.
+ * Form submission handler for forum_confirm_delete().
  */
 function forum_confirm_delete_submit($form, &$form_state) {
   taxonomy_term_delete($form_state['values']['tid']);
@@ -202,9 +227,11 @@ function forum_confirm_delete_submit($form, &$form_state) {
 }
 
 /**
- * Form builder for the forum settings page.
+ * Form constructor for the forum settings page.
  *
+ * @see forum_menu()
  * @see system_settings_form()
+ * @ingroup forms
  */
 function forum_admin_settings($form) {
   $number = drupal_map_assoc(array(5, 10, 15, 20, 25, 30, 35, 40, 50, 60, 80, 100, 150, 200, 250, 300, 350, 400, 500));
@@ -232,7 +259,13 @@ function forum_admin_settings($form) {
 }
 
 /**
- * Returns an overview list of existing forums and containers
+ * Form constructor for the forum overview form.
+ *
+ * Returns a form for controlling the hierarchy of existing forums and
+ * containers.
+ *
+ * @see forum_menu()
+ * @ingroup forms
  */
 function forum_overview($form, &$form_state) {
   module_load_include('inc', 'taxonomy', 'taxonomy.admin');
@@ -267,11 +300,17 @@ function forum_overview($form, &$form_state) {
 }
 
 /**
- * Returns a select box for available parent terms
+ * Returns a select box for available parent terms.
+ *
+ * @param $tid
+ *   ID of the term that is being added or edited.
+ * @param $title
+ *   Title for the select box.
+ * @param $child_type
+ *   Whether the child is a forum or a container.
  *
- * @param $tid ID of the term which is being added or edited
- * @param $title Title to display the select box with
- * @param $child_type Whether the child is forum or container
+ * @return
+ *   A select form element.
  */
 function _forum_parent_select($tid, $title, $child_type) {
 
diff --git a/modules/forum/forum.css b/modules/forum/forum.css
index 4a67c8bcd..a758bc666 100644
--- a/modules/forum/forum.css
+++ b/modules/forum/forum.css
@@ -1,3 +1,7 @@
+/**
+ * @file
+ * Styling for the Forum module.
+ */
 
 #forum .description {
   font-size: 0.9em;
diff --git a/modules/forum/forum.install b/modules/forum/forum.install
index 558439079..57e116b71 100644
--- a/modules/forum/forum.install
+++ b/modules/forum/forum.install
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Install, update and uninstall functions for the forum module.
+ * Install, update, and uninstall functions for the Forum module.
  */
 
 /**
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:
diff --git a/modules/forum/forum.pages.inc b/modules/forum/forum.pages.inc
index 29307e719..8538310ac 100644
--- a/modules/forum/forum.pages.inc
+++ b/modules/forum/forum.pages.inc
@@ -2,11 +2,20 @@
 
 /**
  * @file
- * User page callbacks for the forum module.
+ * User page callbacks for the Forum module.
  */
 
 /**
- * Menu callback; prints a forum listing.
+ * Page callback: Prints a forum listing.
+ *
+ * @param $forum_term
+ *   A tree of all forums for a given taxonomy term ID. Defaults to NULL. See
+ *   the return object of forum_forum_load() for a complete definition.
+ *
+ * @return
+ *   A string containing HTML representing the themed forum listing.
+ *
+ * @see forum_menu()
  */
 function forum_page($forum_term = NULL) {
   if (!isset($forum_term)) {
diff --git a/modules/forum/forum.test b/modules/forum/forum.test
index 612b09cff..d78d962de 100644
--- a/modules/forum/forum.test
+++ b/modules/forum/forum.test
@@ -5,14 +5,49 @@
  * Tests for forum.module.
  */
 
+/**
+ * Provides automated tests for the Forum module.
+ */
 class ForumTestCase extends DrupalWebTestCase {
+
+  /**
+   * A user with various administrative privileges.
+   */
   protected $admin_user;
+
+  /**
+   * A user that can create forum topics and edit its own topics.
+   */
   protected $edit_own_topics_user;
+
+  /**
+   * A user that can create, edit, and delete forum topics.
+   */
   protected $edit_any_topics_user;
+
+  /**
+   * A user with no special privileges.
+   */
   protected $web_user;
+
+  /**
+   * An array representing a container.
+   */
   protected $container;
+
+  /**
+   * An array representing a forum.
+   */
   protected $forum;
+
+  /**
+   * An array representing a root forum.
+   */
   protected $root_forum;
+
+  /**
+   * An array of forum topic node IDs.
+   */
   protected $nids;
 
   public static function getInfo() {
@@ -23,9 +58,6 @@ class ForumTestCase extends DrupalWebTestCase {
     );
   }
 
-  /**
-   * Enable modules and create users with specific permissions.
-   */
   function setUp() {
     parent::setUp('taxonomy', 'comment', 'forum');
     // Create users.
@@ -53,12 +85,12 @@ class ForumTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Tests disabling and re-enabling forum.
+   * Tests disabling and re-enabling the Forum module.
    */
   function testEnableForumField() {
     $this->drupalLogin($this->admin_user);
 
-    // Disable the forum module.
+    // Disable the Forum module.
     $edit = array();
     $edit['modules[Core][forum][enable]'] = FALSE;
     $this->drupalPost('admin/modules', $edit, t('Save configuration'));
@@ -66,7 +98,7 @@ class ForumTestCase extends DrupalWebTestCase {
     module_list(TRUE);
     $this->assertFalse(module_exists('forum'), t('Forum module is not enabled.'));
 
-    // Attempt to re-enable the forum module and ensure it does not try to
+    // Attempt to re-enable the Forum module and ensure it does not try to
     // recreate the taxonomy_forums field.
     $edit = array();
     $edit['modules[Core][forum][enable]'] = 'forum';
@@ -77,7 +109,7 @@ class ForumTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Login users, create forum nodes, and test forum functionality through the admin and user interfaces.
+   * Tests forum functionality through the admin and user interfaces.
    */
   function testForum() {
     //Check that the basic forum install creates a default forum topic
@@ -168,7 +200,10 @@ class ForumTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Forum nodes should not be created without choosing forum from select list.
+   * Tests that forum nodes can't be added without a parent.
+   *
+   * Verifies that forum nodes are not created without choosing "forum" from the
+   * select list.
    */
   function testAddOrphanTopic() {
     // Must remove forum topics to test creating orphan topics.
@@ -190,9 +225,10 @@ class ForumTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Run admin tests on the admin user.
+   * Runs admin tests on the admin user.
    *
-   * @param object $user The logged in user.
+   * @param object $user
+   *   The logged in user.
    */
   private function doAdminTests($user) {
     // Login the user.
@@ -270,7 +306,7 @@ class ForumTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Edit the forum taxonomy.
+   * Edits the forum taxonomy.
    */
   function editForumTaxonomy() {
     // Backup forum taxonomy.
@@ -308,15 +344,16 @@ class ForumTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Create a forum container or a forum.
+   * Creates a forum container or a forum.
    *
    * @param $type
-   *   Forum type (forum container or forum).
+   *   The forum type (forum container or forum).
    * @param $parent
-   *   Forum parent (default = 0 = a root forum; >0 = a forum container or
+   *   The forum parent. This defaults to 0, indicating a root forum.
    *   another forum).
+   *
    * @return
-   *   taxonomy_term_data created.
+   *   The created taxonomy term data.
    */
   function createForum($type, $parent = 0) {
     // Generate a random name/description.
@@ -349,7 +386,7 @@ class ForumTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Delete a forum.
+   * Deletes a forum.
    *
    * @param $tid
    *   The forum ID.
@@ -370,7 +407,7 @@ class ForumTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Run basic tests on the indicated user.
+   * Runs basic tests on the indicated user.
    *
    * @param $user
    *   The logged in user.
@@ -389,15 +426,15 @@ class ForumTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Create forum topic.
+   * Creates forum topic.
    *
    * @param array $forum
-   *   Forum array.
+   *   A forum array.
    * @param boolean $container
-   *   True if $forum is a container.
+   *   TRUE if $forum is a container; FALSE otherwise.
    *
    * @return object
-   *   Topic node created.
+   *   The created topic node.
    */
   function createForumTopic($forum, $container = FALSE) {
     // Generate a random subject/body.
@@ -439,7 +476,7 @@ class ForumTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Verify the logged in user has access to a forum nodes.
+   * Verifies that the logged in user has access to a forum nodes.
    *
    * @param $node_user
    *   The user who creates the node.
@@ -519,10 +556,12 @@ class ForumTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Verify display of forum page.
+   * Verifies display of forum page.
    *
    * @param $forum
-   *   A row from taxonomy_term_data table in array.
+   *   A row from the taxonomy_term_data table in an array.
+   * @param $parent
+   *   (optional) An array representing the forum's parent.
    */
   private function verifyForumView($forum, $parent = NULL) {
     // View forum page.
@@ -542,9 +581,10 @@ class ForumTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Generate forum topics to test display of active forum block.
+   * Generates forum topics to test the display of an active forum block.
    *
-   * @param array $forum Forum array (a row from taxonomy_term_data table).
+   * @param array $forum
+   *   The foorum array (a row from taxonomy_term_data table).
    */
   private function generateForumTopics($forum) {
     $this->nids = array();
@@ -555,10 +595,10 @@ class ForumTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * View forum topics to test display of active forum block.
+   * Views forum topics to test the display of an active forum block.
    *
-   * @todo The logic here is completely incorrect, since the active
-   * forum topics block is determined by comments on the node, not by views.
+   * @todo The logic here is completely incorrect, since the active forum topics
+   *   block is determined by comments on the node, not by views.
    * @todo DIE
    *
    * @param $nids
diff --git a/modules/forum/forums.tpl.php b/modules/forum/forums.tpl.php
index 55a760f57..01919ab6a 100644
--- a/modules/forum/forums.tpl.php
+++ b/modules/forum/forums.tpl.php
@@ -2,16 +2,19 @@
 
 /**
  * @file
- * Default theme implementation to display a forum which may contain forum
- * containers as well as forum topics.
+ * Displays a forum.
  *
- * Variables available:
- * - $forums: The forums to display (as processed by forum-list.tpl.php)
- * - $topics: The topics to display (as processed by forum-topic-list.tpl.php)
+ * May contain forum containers as well as forum topics.
+ *
+ * Available variables:
+ * - $forums: The forums to display (as processed by forum-list.tpl.php).
+ * - $topics: The topics to display (as processed by forum-topic-list.tpl.php).
  * - $forums_defined: A flag to indicate that the forums are configured.
  *
  * @see template_preprocess_forums()
  * @see theme_forums()
+ *
+ * @ingroup themeable
  */
 ?>
 <?php if ($forums_defined): ?>