commit 604ed35d558ca99408d91c90d54ac93f1d41061c
Author: jstoller <jeremy@stollerdesign.com>
Date:   Fri Apr 27 12:55:01 2012 -0700

    Patch 33.
    
    Conflicts:
    
    	core/modules/forum/forum-submitted.tpl.php
    	core/modules/forum/forum.admin.inc
    	core/modules/forum/forum.module
    	core/modules/forum/forum.pages.inc
    	core/modules/forum/forum.test

diff --git a/core/modules/forum/forum-submitted.tpl.php b/core/modules/forum/forum-submitted.tpl.php
index 66c4908..18fea8f 100644
--- a/core/modules/forum/forum-submitted.tpl.php
+++ b/core/modules/forum/forum-submitted.tpl.php
@@ -9,8 +9,8 @@
  * 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()
diff --git a/core/modules/forum/forum.admin.inc b/core/modules/forum/forum.admin.inc
index 87749bb..1c68687 100644
--- a/core/modules/forum/forum.admin.inc
+++ b/core/modules/forum/forum.admin.inc
@@ -11,8 +11,8 @@
  * @param $type
  *   What is being added. Possible values are 'forum' and 'container'.
  * @param $edit
- *   Associative array containing a forum term to be edited. Defaults to an
- *   empty array.
+ *   (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.
@@ -38,7 +38,8 @@ function forum_form_main($type, $edit = array()) {
  * Form constructor for adding and editing a forum.
  *
  * @param $edit
- *   Associative array containing a forum term to be added or edited.
+ *   (optional) Associative array containing a forum term to be added or edited.
+ *   Defaults to an empty array.
  *
  * @see forum_form_submit()
  * @ingroup forms
@@ -140,7 +141,8 @@ function theme_forum_form($variables) {
  * Form constructor for adding and editing forum containers.
  *
  * @param $edit
- *   Associative array containing a container term to be added or edited.
+ *   (optional) Associative array containing a container term to be added or edited.
+ *   Defaults to an empty array.
  *
  * @see forum_form_submit()
  * @ingroup forms
diff --git a/core/modules/forum/forum.module b/core/modules/forum/forum.module
index 6a6ec93..5bc451d 100644
--- a/core/modules/forum/forum.module
+++ b/core/modules/forum/forum.module
@@ -495,11 +495,11 @@ function forum_comment_publish($comment) {
  * Implements hook_comment_update().
  *
  * The Comment module doesn't call hook_comment_unpublish() when saving
- * individual comments so we need to check for those here.
+ * 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);
   }
@@ -721,7 +721,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);
@@ -734,7 +734,7 @@ 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 given all forums will be
+ *   (optional) Taxonomy term ID of the forum. If not given all forums will be
  *   returned.
  *
  * @return
@@ -973,7 +973,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;
       }
@@ -1023,12 +1024,18 @@ function forum_preprocess_block(&$variables) {
  *
  * @param $variables
  *   An array containing the following elements:
- *   - forums
- *   - topics
- *   - parents
- *   - tid
- *   - sortby
- *   - forum_per_page
+ *   - 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
  */
@@ -1103,9 +1110,11 @@ function template_preprocess_forums(&$variables) {
  *
  * @param $variables
  *   An array containing the following elements:
- *   - forums
- *   - parents
- *   - tid
+ *   - 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()
@@ -1150,10 +1159,9 @@ function template_preprocess_forum_list(&$variables) {
  *
  * @param $variables
  *   An array containing the following elements:
- *   - tid
- *   - topics
- *   - sortby
- *   - forum_per_page
+ *   - 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()
@@ -1203,7 +1211,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.
@@ -1218,11 +1226,12 @@ function template_preprocess_forum_topic_list(&$variables) {
  *
  * @param $variables
  *   An array containing the following elements:
- *   - new_posts
- *   - num_posts = 0
- *   - comment_mode = 0
- *   - sticky = 0
- *   - first_new
+ *   - 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 if comments are open, closed, or
+ *     hidden.
+ *   - sticky: Indicates if 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()
@@ -1257,7 +1266,7 @@ function template_preprocess_forum_icon(&$variables) {
  *
  * @param $variables
  *   An array containing the following elements:
- *   - topic
+ *   - topic: The topic object.
  *
  * @see forum-submitted.tpl.php
  * @see theme_forum_submitted()
diff --git a/core/modules/forum/forum.pages.inc b/core/modules/forum/forum.pages.inc
index b687778..8538310 100644
--- a/core/modules/forum/forum.pages.inc
+++ b/core/modules/forum/forum.pages.inc
@@ -13,7 +13,7 @@
  *   the return object of forum_forum_load() for a complete definition.
  *
  * @return
- *   Themed forum listing.
+ *   A string containing HTML representing the themed forum listing.
  *
  * @see forum_menu()
  */
diff --git a/core/modules/forum/forum.test b/core/modules/forum/forum.test
index 6550ea6..c38f8c0 100644
--- a/core/modules/forum/forum.test
+++ b/core/modules/forum/forum.test
@@ -8,7 +8,7 @@
 use Drupal\node\Node;
 
 /**
- * Represents a test case for menu administration.
+ * Provides automated tests for the Forum module.
  */
 class ForumTestCase extends DrupalWebTestCase {
 
@@ -233,7 +233,7 @@ class ForumTestCase extends DrupalWebTestCase {
    * Runs admin tests on the admin user.
    *
    * @param object $user
-   *   The logged in user.
+   *   The logged-in user.
    */
   private function doAdminTests($user) {
     // Login the user.
@@ -365,8 +365,7 @@ class ForumTestCase extends DrupalWebTestCase {
    * @param $type
    *   The forum type (forum container or forum).
    * @param $parent
-   *   The forum parent (default = 0 = a root forum; >0 = a forum container or
-   *   another forum).
+   *   The forum parent. This defaults to 0, indicating a root forum.
    *
    * @return
    *   The created taxonomy term data.
@@ -447,7 +446,7 @@ class ForumTestCase extends DrupalWebTestCase {
    * @param array $forum
    *   A forum array.
    * @param boolean $container
-   *   TRUE if $forum is a container, FALSE otherwise.
+   *   TRUE if $forum is a container; FALSE otherwise.
    *
    * @return object
    *   The created topic node.