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..63f132a 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
+ * Processes 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.
+ * Processes 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.
+ * Processes 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.
+ * Processes 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/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
*/
?>