Commit 0da848d5 authored by jhodgdon's avatar jhodgdon

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.
*/
/**
......
This diff is collapsed.
......@@ -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)) {
......
......@@ -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): ?>
......
......@@ -2,7 +2,7 @@
/**
* @file
* Definition of Drupal\forum\Tests\ForumTest.
* Tests for forum.module.
*/
namespace Drupal\forum\Tests;
......@@ -10,14 +10,49 @@
use Drupal\node\Node;
use Drupal\simpletest\WebTestBase;
/**
* Provides automated tests for the Forum module.
*/
class ForumTest extends WebTestBase {
/**
* 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() {
......@@ -28,9 +63,6 @@ public static function getInfo() {
);
}
/**
* Enable modules and create users with specific permissions.
*/
function setUp() {
parent::setUp(array('taxonomy', 'comment', 'forum', 'node', 'block', 'menu', 'help'));
// Create users.
......@@ -58,12 +90,12 @@ function setUp() {
}
/**
* 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'));
......@@ -71,7 +103,7 @@ function testEnableForumField() {
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';
......@@ -82,7 +114,7 @@ function testEnableForumField() {
}
/**
* 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
......@@ -176,7 +208,10 @@ function testForum() {
}
/**
* 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.
......@@ -198,9 +233,10 @@ function testAddOrphanTopic() {
}
/**
* 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.
......@@ -289,7 +325,7 @@ private function doAdminTests($user) {
}
/**
* Edit the forum taxonomy.
* Edits the forum taxonomy.
*/
function editForumTaxonomy() {
// Backup forum taxonomy.
......@@ -327,15 +363,15 @@ function editForumTaxonomy() {
}
/**
* 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
* another forum).
* The forum parent. This defaults to 0, indicating a root forum.
*
* @return
* taxonomy_term_data created.
* The created taxonomy term data.
*/
function createForum($type, $parent = 0) {
// Generate a random name/description.
......@@ -368,7 +404,7 @@ function createForum($type, $parent = 0) {
}
/**
* Delete a forum.
* Deletes a forum.
*
* @param $tid
* The forum ID.
......@@ -389,7 +425,7 @@ function deleteForum($tid) {
}
/**
* Run basic tests on the indicated user.
* Runs basic tests on the indicated user.
*
* @param $user
* The logged in user.
......@@ -408,15 +444,15 @@ private function doBasicTests($user, $admin) {
}
/**
* 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.
......@@ -458,7 +494,7 @@ function createForumTopic($forum, $container = FALSE) {
}
/**
* 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.
......@@ -538,10 +574,12 @@ private function verifyForums($node_user, Node $node, $admin, $response = 200) {
}
/**
* 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.
......@@ -561,9 +599,10 @@ private function verifyForumView($forum, $parent = NULL) {
}
/**
* 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();
......@@ -574,10 +613,10 @@ private function generateForumTopics($forum) {
}
/**
* 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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment