Commit 0da848d5 authored by jhodgdon's avatar jhodgdon
Browse files

Issue #1357138 by jstoller, xenophyle: Clean up API docs for Forum module

parent 47592120
......@@ -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 ?>">
......
......@@ -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; ?>">
......
/**
* @file
* Right-to-left styling for the Forum module.
*/
#forum td.forum .icon {
float: right;
......
......@@ -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): ?>
......
......@@ -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; ?>">
......
......@@ -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') {
......@@ -106,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:
......@@ -120,11 +138,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(
......@@ -178,9 +199,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);
......@@ -192,7 +217,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']);
......@@ -204,9 +229,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));
......@@ -234,7 +261,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');
......@@ -270,11 +303,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) {
......
/**
* @file
* Styling for the Forum module.
*/
#forum .description {
font-size: 0.9em;
......
......@@ -2,7 +2,7 @@
/**
* @file
* Install, update and uninstall functions for the forum module.
* Install, update, and uninstall functions for the Forum module.
*/
/**
......
......@@ -236,7 +236,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(
......@@ -245,7 +245,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 Drupal\node\Node $node
* A node entity.
......@@ -286,7 +286,8 @@ function forum_node_view(Node $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 $node, $form) {
if (_forum_node_check_node_type($node)) {
......@@ -322,7 +323,7 @@ function forum_node_validate(Node $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 $node) {
if (_forum_node_check_node_type($node)) {
......@@ -484,7 +485,7 @@ function forum_taxonomy_term_delete(Term $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) {
......@@ -494,12 +495,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);
}
......@@ -672,8 +673,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')
......@@ -703,13 +704,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)) {
......@@ -733,7 +733,7 @@ function forum_form(Node $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);
......@@ -746,13 +746,15 @@ function forum_form(Node $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());
......@@ -859,8 +861,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');
......@@ -876,6 +887,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;
......@@ -959,7 +987,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;
}
......@@ -1005,15 +1034,22 @@ function forum_preprocess_block(&$variables) {
}
/**
* 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
*/
......@@ -1084,12 +1120,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()
......@@ -1130,13 +1169,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()
......@@ -1186,7 +1225,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.
......@@ -1197,14 +1236,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()
......@@ -1232,9 +1273,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()
......@@ -1244,6 +1290,16 @@ function template_preprocess_forum_submitted(&$variables) {
$variables['time'] = isset($variables['topic']->created) ? format_interval(REQUEST_TIME - $variables['topic']->created) : '';
}