diff --git a/core/modules/forum/forum-icon.tpl.php b/core/modules/forum/forum-icon.tpl.php
index 9cf2cd8..fd1cd13 100644
--- a/core/modules/forum/forum-icon.tpl.php
+++ b/core/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
*/
?>
diff --git a/core/modules/forum/forum-list.tpl.php b/core/modules/forum/forum-list.tpl.php
index 257cea9..1adcb5c 100644
--- a/core/modules/forum/forum-list.tpl.php
+++ b/core/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: 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.
+ * - $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
*/
?>
diff --git a/core/modules/forum/forum-submitted.tpl.php b/core/modules/forum/forum-submitted.tpl.php
index d310448..66c4908 100644
--- a/core/modules/forum/forum-submitted.tpl.php
+++ b/core/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. Unsafe: be sure to clean
+ * this data before printing.
*
* @see template_preprocess_forum_submitted()
* @see theme_forum_submitted()
+ *
+ * @ingroup themeable
*/
?>
diff --git a/core/modules/forum/forum-topic-list.tpl.php b/core/modules/forum/forum-topic-list.tpl.php
index 3390703..36dfb6f 100644
--- a/core/modules/forum/forum-topic-list.tpl.php
+++ b/core/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: An outputtable string representing 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.
+ * - $topic_id: Numeric ID for the current forum topic.
*
* @see template_preprocess_forum_topic_list()
* @see theme_forum_topic_list()
+ *
+ * @ingroup themeable
*/
?>
diff --git a/core/modules/forum/forum.admin.inc b/core/modules/forum/forum.admin.inc
index 49c71d9..6c65811 100644
--- a/core/modules/forum/forum.admin.inc
+++ b/core/modules/forum/forum.admin.inc
@@ -4,6 +4,24 @@
* @file
* Administrative page callbacks for the forum module.
*/
+
+/**
+ * Page callback: Returns a form for creating a new forum or container.
+ *
+ * Path:
+ * - admin/structure/forum/add/container
+ * - admin/structure/forum/add/forum
+ * - admin/structure/forum/edit/container/%taxonomy_term
+ * - admin/structure/forum/edit/forum/%taxonomy_term
+ *
+ * @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.
+ *
+ * @see forum_menu()
+ */
function forum_form_main($type, $edit = array()) {
$edit = (array) $edit;
if ((isset($_POST['op']) && $_POST['op'] == t('Delete')) || !empty($_POST['confirm'])) {
@@ -20,11 +38,13 @@ 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
+ * Associative array containing a forum term to be added or edited.
*
- * @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 +87,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 +124,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 +138,13 @@ 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
+ * Associative array containing a container term to be added or edited.
*
- * @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 +198,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 +216,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 +228,13 @@ function forum_confirm_delete_submit($form, &$form_state) {
}
/**
- * Form builder for the forum settings page.
+ * Form constructor for the forum settings page.
*
+ * Path: admin/structure/forum/settings
+ *
+ * @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 +262,15 @@ function forum_admin_settings($form) {
}
/**
- * Returns an overview list of existing forums and containers
+ * Form constructor for the forum overview form.
+ *
+ * Path: admin/structure/forum
+ *
+ * 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 +305,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/core/modules/forum/forum.module b/core/modules/forum/forum.module
index 3575bfd..9f747cd 100644
--- a/core/modules/forum/forum.module
+++ b/core/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($tid) {
/**
* 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,8 +492,8 @@ 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
@@ -650,8 +651,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')
@@ -681,13 +682,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)) {
@@ -724,13 +724,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 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());
@@ -838,8 +840,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');
@@ -855,6 +866,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;
@@ -962,15 +990,16 @@ 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
+ * - topics
+ * - parents
+ * - tid
+ * - sortby
+ * - forum_per_page
*
* @see forums.tpl.php
*/
@@ -1041,12 +1070,13 @@ function template_preprocess_forums(&$variables) {
}
/**
- * Process variables to format a forum listing.
+ * Preprocesses variables to format a forum listing.
*
- * $variables contains the following information:
- * - $forums
- * - $parents
- * - $tid
+ * @param $variables
+ * An array containing the following elements:
+ * - forums
+ * - parents
+ * - tid
*
* @see forum-list.tpl.php
* @see theme_forum_list()
@@ -1087,13 +1117,14 @@ function template_preprocess_forum_list(&$variables) {
}
/**
- * Preprocess variables to format the topic listing.
+ * Preprocesses variables to format the topic listing.
*
- * $variables contains the following data:
- * - $tid
- * - $topics
- * - $sortby
- * - $forum_per_page
+ * @param $variables
+ * An array containing the following elements:
+ * - tid
+ * - topics
+ * - sortby
+ * - forum_per_page
*
* @see forum-topic-list.tpl.php
* @see theme_forum_topic_list()
@@ -1154,14 +1185,15 @@ function template_preprocess_forum_topic_list(&$variables) {
}
/**
- * Process variables to format the icon for each individual topic.
+ * Preprocesses variables to format the icon for each individual topic.
*
- * $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
+ * - num_posts = 0
+ * - comment_mode = 0
+ * - sticky = 0
+ * - first_new
*
* @see forum-icon.tpl.php
* @see theme_forum_icon()
@@ -1189,9 +1221,14 @@ function template_preprocess_forum_icon(&$variables) {
}
/**
- * Process variables to format submission info for display in the forum list and topic list.
+ * Preprocesses variables to format submission information.
+ *
+ * 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
*
* @see forum-submitted.tpl.php
* @see theme_forum_submitted()
@@ -1201,6 +1238,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
+ * If the user has previously viewed the node, returns the timestamp of the
+ * view; otherwise returns NODE_NEW_LIMIT.
+ */
function _forum_user_last_visit($nid) {
global $user;
$history = &drupal_static(__FUNCTION__, array());
@@ -1214,6 +1261,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/core/modules/forum/forum.pages.inc b/core/modules/forum/forum.pages.inc
index 29307e7..186dc61 100644
--- a/core/modules/forum/forum.pages.inc
+++ b/core/modules/forum/forum.pages.inc
@@ -6,7 +6,17 @@
*/
/**
- * Menu callback; prints a forum listing.
+ * Page callback: Prints a forum listing.
+ *
+ * Path:
+ * - forum
+ * - forum/%forum_forum
+ *
+ * @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.
+ *
+ * @see forum_menu()
*/
function forum_page($forum_term = NULL) {
if (!isset($forum_term)) {
diff --git a/core/modules/forum/forum.test b/core/modules/forum/forum.test
index c7c3d9c..3147d78 100644
--- a/core/modules/forum/forum.test
+++ b/core/modules/forum/forum.test
@@ -5,16 +5,54 @@
* Tests for forum.module.
*/
+/**
+ * Represents a test case for menu administration.
+ */
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;
+ /**
+ * Returns information about the forum tests.
+ */
public static function getInfo() {
return array(
'name' => 'Forum functionality',
@@ -24,7 +62,7 @@ class ForumTestCase extends DrupalWebTestCase {
}
/**
- * Enable modules and create users with specific permissions.
+ * Implements DrupalWebTestCase::setUp().
*/
function setUp() {
parent::setUp('taxonomy', 'comment', 'forum');
@@ -53,7 +91,7 @@ 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);
@@ -77,7 +115,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 +206,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 +231,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.
@@ -249,7 +291,7 @@ class ForumTestCase extends DrupalWebTestCase {
}
/**
- * Edit the forum taxonomy.
+ * Edits the forum taxonomy.
*/
function editForumTaxonomy() {
// Backup forum taxonomy.
@@ -287,15 +329,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 (default = 0 = a root forum; >0 = a forum container or
* another forum).
+ *
* @return
- * taxonomy_term_data created.
+ * The created taxonomy term data.
*/
function createForum($type, $parent = 0) {
// Generate a random name/description.
@@ -328,7 +371,7 @@ class ForumTestCase extends DrupalWebTestCase {
}
/**
- * Delete a forum.
+ * Deletes a forum.
*
* @param $tid
* The forum ID.
@@ -344,7 +387,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.
@@ -363,15 +406,15 @@ class ForumTestCase extends DrupalWebTestCase {
}
/**
- * Create forum topic.
+ * Creates a 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.
@@ -413,7 +456,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 node.
*
* @param $node_user
* The user who creates the node.
@@ -493,10 +536,12 @@ class ForumTestCase extends DrupalWebTestCase {
}
/**
- * Verify display of forum page.
+ * Verifies the display of a 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.
@@ -516,9 +561,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 forum array (a row from taxonomy_term_data table).
*/
private function generateForumTopics($forum) {
$this->nids = array();
@@ -529,10 +575,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/core/modules/forum/forums.tpl.php b/core/modules/forum/forums.tpl.php
index 55a760f..01919ab 100644
--- a/core/modules/forum/forums.tpl.php
+++ b/core/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
*/
?>