From 37f2b2f26598967f2aa49904e0f83b409954b2b5 Mon Sep 17 00:00:00 2001
From: catch <catch@35733.no-reply.drupal.org>
Date: Tue, 3 Jan 2012 13:36:15 +0900
Subject: [PATCH] Issue #1332598 by sven.lauer: Clean up API docs for comment
module.
---
core/modules/comment/comment-node-form.js | 4 +
core/modules/comment/comment-wrapper.tpl.php | 2 +-
core/modules/comment/comment.admin.inc | 57 +++++--
core/modules/comment/comment.api.php | 41 +++--
core/modules/comment/comment.install | 8 +-
core/modules/comment/comment.module | 164 ++++++++++++-------
core/modules/comment/comment.pages.inc | 16 +-
core/modules/comment/comment.test | 111 +++++++------
core/modules/comment/comment.tpl.php | 10 +-
9 files changed, 252 insertions(+), 161 deletions(-)
diff --git a/core/modules/comment/comment-node-form.js b/core/modules/comment/comment-node-form.js
index 76db2404ea17..e46f05e26896 100644
--- a/core/modules/comment/comment-node-form.js
+++ b/core/modules/comment/comment-node-form.js
@@ -1,3 +1,7 @@
+/**
+ * @file
+ * Attaches comment behaviors to the node form.
+ */
(function ($) {
diff --git a/core/modules/comment/comment-wrapper.tpl.php b/core/modules/comment/comment-wrapper.tpl.php
index d855631a7480..5e58a676724d 100644
--- a/core/modules/comment/comment-wrapper.tpl.php
+++ b/core/modules/comment/comment-wrapper.tpl.php
@@ -2,7 +2,7 @@
/**
* @file
- * Default theme implementation to provide an HTML container for comments.
+ * Provides an HTML container for comments.
*
* Available variables:
* - $content: The array of content-related elements for the node. Use
diff --git a/core/modules/comment/comment.admin.inc b/core/modules/comment/comment.admin.inc
index 4f3d35071536..550de56852dc 100644
--- a/core/modules/comment/comment.admin.inc
+++ b/core/modules/comment/comment.admin.inc
@@ -2,11 +2,20 @@
/**
* @file
- * Admin page callbacks for the comment module.
+ * Admin page callbacks for the Comment module.
*/
/**
- * Menu callback; present an administrative comment listing.
+ * Page callback: Presents an administrative comment listing.
+ *
+ * Path: admin/content/comment
+ *
+ * @param $type
+ * The type of the overview form ('approval' or 'new'). See
+ * comment_admin_overview() for details.
+ *
+ * @see comment_menu()
+ * @see comment_multiple_delete_confirm()
*/
function comment_admin($type = 'new') {
$edit = $_POST;
@@ -20,13 +29,13 @@ function comment_admin($type = 'new') {
}
/**
- * Form builder for the comment overview administration form.
+ * Form constructor for the comment overview administration form.
*
* @param $arg
- * Current path's fourth component: the type of overview form ('approval' or
- * 'new').
+ * The type of overview form ('approval' or 'new').
*
* @ingroup forms
+ * @see comment_admin()
* @see comment_admin_overview_validate()
* @see comment_admin_overview_submit()
* @see theme_comment_admin_overview()
@@ -140,7 +149,9 @@ function comment_admin_overview($form, &$form_state, $arg) {
}
/**
- * Validate comment_admin_overview form submissions.
+ * Form validation handler for comment_admin_overview().
+ *
+ * @see comment_admin_overview_submit()
*/
function comment_admin_overview_validate($form, &$form_state) {
$form_state['values']['comments'] = array_diff($form_state['values']['comments'], array(0));
@@ -151,10 +162,12 @@ function comment_admin_overview_validate($form, &$form_state) {
}
/**
- * Process comment_admin_overview form submissions.
+ * Form submission handler for comment_admin_overview().
*
- * Execute the chosen 'Update option' on the selected comments, such as
+ * Executes the chosen 'Update option' on the selected comments, such as
* publishing, unpublishing or deleting.
+ *
+ * @see comment_admin_overview_validate()
*/
function comment_admin_overview_submit($form, &$form_state) {
$operation = $form_state['values']['operation'];
@@ -182,13 +195,10 @@ function comment_admin_overview_submit($form, &$form_state) {
}
/**
- * List the selected comments and verify that the admin wants to delete them.
+ * Form constructor for the confirmation form for bulk comment deletion.
*
- * @param $form_state
- * An associative array containing the current state of the form.
- * @return
- * TRUE if the comments should be deleted, FALSE otherwise.
* @ingroup forms
+ * @see comment_admin()
* @see comment_multiple_delete_confirm_submit()
*/
function comment_multiple_delete_confirm($form, &$form_state) {
@@ -224,7 +234,7 @@ function comment_multiple_delete_confirm($form, &$form_state) {
}
/**
- * Process comment_multiple_delete_confirm form submissions.
+ * Form submission handler for comment_multiple_delete_confirm().
*/
function comment_multiple_delete_confirm_submit($form, &$form_state) {
if ($form_state['values']['confirm']) {
@@ -238,7 +248,15 @@ function comment_multiple_delete_confirm_submit($form, &$form_state) {
}
/**
- * Page callback for comment deletions.
+ * Page callback: Shows a confirmation page for comment deletions.
+ *
+ * Path: comment/%/delete
+ *
+ * @param $cid
+ * The ID of the comment that is about to be deleted.
+ *
+ * @see comment_menu()
+ * @see comment_confirm_delete()
*/
function comment_confirm_delete_page($cid) {
if ($comment = comment_load($cid)) {
@@ -248,10 +266,15 @@ function comment_confirm_delete_page($cid) {
}
/**
- * Form builder; Builds the confirmation form for deleting a single comment.
+ * Form constructor for the confirmation form for comment deletion.
+ *
+ * @param $comment
+ * The comment that is about to be deleted.
*
* @ingroup forms
+ * @see comment_confirm_delete_page()
* @see comment_confirm_delete_submit()
+ * @see confirm_form()
*/
function comment_confirm_delete($form, &$form_state, $comment) {
$form['#comment'] = $comment;
@@ -268,7 +291,7 @@ function comment_confirm_delete($form, &$form_state, $comment) {
}
/**
- * Process comment_confirm_delete form submissions.
+ * Form submission handler for comment_confirm_delete().
*/
function comment_confirm_delete_submit($form, &$form_state) {
$comment = $form['#comment'];
diff --git a/core/modules/comment/comment.api.php b/core/modules/comment/comment.api.php
index b381b6cfc4bd..f270aadade11 100644
--- a/core/modules/comment/comment.api.php
+++ b/core/modules/comment/comment.api.php
@@ -11,9 +11,10 @@
*/
/**
- * The comment passed validation and is about to be saved.
+ * Act on a comment being inserted or updated.
*
- * Modules may make changes to the comment before it is saved to the database.
+ * This hook is invoked from comment_save() before the comment is saved to the
+ * database.
*
* @param $comment
* The comment object.
@@ -24,7 +25,7 @@ function hook_comment_presave($comment) {
}
/**
- * The comment is being inserted.
+ * Respond to creation of a new comment.
*
* @param $comment
* The comment object.
@@ -35,7 +36,7 @@ function hook_comment_insert($comment) {
}
/**
- * The comment is being updated.
+ * Respond to updates to a comment.
*
* @param $comment
* The comment object.
@@ -46,7 +47,7 @@ function hook_comment_update($comment) {
}
/**
- * Comments are being loaded from the database.
+ * Act on comments being loaded from the database.
*
* @param $comments
* An array of comment objects indexed by cid.
@@ -59,7 +60,7 @@ function hook_comment_load($comments) {
}
/**
- * The comment is being viewed. This hook can be used to add additional data to the comment before theming.
+ * Act on a comment that is being assembled before rendering.
*
* @param $comment
* Passes in the comment the action is being performed on.
@@ -76,16 +77,16 @@ function hook_comment_view($comment, $view_mode, $langcode) {
}
/**
- * The comment was built; the module may modify the structured content.
+ * Alter the results of comment_view().
*
- * This hook is called after the content has been assembled in a structured array
- * and may be used for doing processing which requires that the complete comment
- * content structure has been built.
+ * This hook is called after the content has been assembled in a structured
+ * array and may be used for doing processing which requires that the complete
+ * comment content structure has been built.
*
- * If the module wishes to act on the rendered HTML of the comment rather than the
- * structured content array, it may use this hook to add a #post_render callback.
- * Alternatively, it could also implement hook_preprocess_comment(). See
- * drupal_render() and theme() documentation respectively for details.
+ * If the module wishes to act on the rendered HTML of the comment rather than
+ * the structured content array, it may use this hook to add a #post_render
+ * callback. Alternatively, it could also implement hook_preprocess_comment().
+ * See drupal_render() and theme() documentation respectively for details.
*
* @param $build
* A renderable array representing the comment.
@@ -105,24 +106,20 @@ function hook_comment_view_alter(&$build) {
}
/**
- * The comment is being published by the moderator.
+ * Respond to a comment being published by a moderator.
*
* @param $comment
- * Passes in the comment the action is being performed on.
- * @return
- * Nothing.
+ * The comment the action is being performed on.
*/
function hook_comment_publish($comment) {
drupal_set_message(t('Comment: @subject has been published', array('@subject' => $comment->subject)));
}
/**
- * The comment is being unpublished by the moderator.
+ * Respond to a comment being unpublished by a moderator.
*
* @param $comment
- * Passes in the comment the action is being performed on.
- * @return
- * Nothing.
+ * The comment the action is being performed on.
*/
function hook_comment_unpublish($comment) {
drupal_set_message(t('Comment: @subject has been unpublished', array('@subject' => $comment->subject)));
diff --git a/core/modules/comment/comment.install b/core/modules/comment/comment.install
index 9c4a2d8ab8b4..c1be4931d9d5 100644
--- a/core/modules/comment/comment.install
+++ b/core/modules/comment/comment.install
@@ -2,7 +2,7 @@
/**
* @file
- * Install, update and uninstall functions for the comment module.
+ * Install, update and uninstall functions for the Comment module.
*/
/**
@@ -51,10 +51,10 @@ function comment_enable() {
/**
* Implements hook_modules_enabled().
*
- * Creates comment body fields for node types existing before the comment module
+ * Creates comment body fields for node types existing before the Comment module
* is enabled. We use hook_modules_enabled() rather than hook_enable() so we can
* react to node types of existing modules, and those of modules being enabled
- * both before and after comment module in the loop of module_enable().
+ * both before and after the Comment module in the loop of module_enable().
*
* There is a separate comment bundle for each node type to allow for
* per-node-type customization of comment fields. Each one of these bundles
@@ -65,7 +65,7 @@ function comment_enable() {
* @see comment_node_type_insert()
*/
function comment_modules_enabled($modules) {
- // Only react if comment module is one of the modules being enabled.
+ // Only react if the Comment module is one of the modules being enabled.
// hook_node_type_insert() is used to create body fields while the comment
// module is enabled.
if (in_array('comment', $modules)) {
diff --git a/core/modules/comment/comment.module b/core/modules/comment/comment.module
index e5e636b90ec4..d69ea9415508 100644
--- a/core/modules/comment/comment.module
+++ b/core/modules/comment/comment.module
@@ -4,9 +4,9 @@
* @file
* Enables users to comment on published content.
*
- * When enabled, the Drupal comment module creates a discussion
- * board for each Drupal node. Users can post comments to discuss
- * a forum topic, story, collaborative book page, etc.
+ * When enabled, the Comment module creates a discussion board for each Drupal
+ * node. Users can post comments to discuss a forum topic, story, collaborative
+ * book page, etc.
*/
/**
@@ -141,9 +141,19 @@ function comment_entity_info() {
}
/**
- * Menu loader callback for Field UI paths.
+ * Loads the comment bundle name corresponding a given content type.
*
- * Return a comment bundle name from a node type in the URL.
+ * This function is used as a menu loader callback in comment_menu().
+ *
+ * @param $name
+ * The URL-formatted machine name of the node type whose comment fields are
+ * to be edited. 'URL-formatted' means that underscores are replaced by
+ * hyphens.
+ *
+ * @return
+ * The comment bundle name corresponding to the node type.
+ *
+ * @see comment_menu_alter()
*/
function comment_node_type_load($name) {
if ($type = node_type_get_type(strtr($name, array('-' => '_')))) {
@@ -318,8 +328,8 @@ function comment_count_unpublished() {
/**
* Implements hook_node_type_insert().
*
- * Creates a comment body field for a node type created while the comment module
- * is enabled. For node types created before the comment module is enabled,
+ * Creates a comment body field for a node type created while the Comment module
+ * is enabled. For node types created before the Comment module is enabled,
* hook_modules_enabled() serves to create the body fields.
*
* @see comment_modules_enabled()
@@ -358,6 +368,11 @@ function comment_node_type_delete($info) {
/**
* Creates a comment_body field instance for a given node type.
+ *
+ * @param $info
+ * An object representing the content type. The only property that is
+ * currently used is $info->type, which is the machine name of the content
+ * type for which the body field (instance) is to be created.
*/
function _comment_body_field_create($info) {
// Create the field if needed.
@@ -473,6 +488,7 @@ function comment_block_view($delta = '') {
*
* @param $cid
* A comment identifier.
+ *
* @return
* The comment listing set to the page on which the comment appears.
*/
@@ -494,7 +510,7 @@ function comment_permalink($cid) {
}
/**
- * Find the most recent comments that are available to the current user.
+ * Finds the most recent comments that are available to the current user.
*
* @param integer $number
* (optional) The maximum number of comments to find. Defaults to 10.
@@ -523,7 +539,7 @@ function comment_get_recent($number = 10) {
}
/**
- * Calculate page number for first new comment.
+ * Calculates the page number for the first new comment.
*
* @param $num_comments
* Number of comments.
@@ -531,6 +547,7 @@ function comment_get_recent($number = 10) {
* Number of new replies.
* @param $node
* The first new comment node.
+ *
* @return
* "page=X" if the page number is greater than zero; empty string otherwise.
*/
@@ -590,7 +607,7 @@ function comment_new_page_count($num_comments, $new_replies, $node) {
}
/**
- * Returns HTML for a list of recent comments to be displayed in the comment block.
+ * Returns HTML for a list of recent comments.
*
* @ingroup themeable
*/
@@ -714,10 +731,14 @@ function comment_node_view($node, $view_mode) {
}
/**
- * Build the comment-related elements for node detail pages.
+ * Builds the comment-related elements for node detail pages.
*
* @param $node
- * A node object.
+ * The node object for which to build the comment-related elements.
+ *
+ * @return
+ * A renderable array representing the comment-related page elements for the
+ * node.
*/
function comment_node_page_additions($node) {
$additions = array();
@@ -756,7 +777,7 @@ function comment_node_page_additions($node) {
}
/**
- * Retrieve comments for a thread.
+ * Retrieves comments for a thread.
*
* @param $node
* The node whose comment(s) needs rendering.
@@ -765,6 +786,9 @@ function comment_node_page_additions($node) {
* @param $comments_per_page
* The amount of comments to display per page.
*
+ * @return
+ * An array of the IDs of the comment to be displayed.
+ *
* To display threaded comments in the correct order we keep a 'thread' field
* and order by that value. This field keeps this data in
* a way which is easy to update and convenient to use.
@@ -859,12 +883,14 @@ function comment_get_thread($node, $mode, $comments_per_page) {
}
/**
- * Loop over comment thread, noting indentation level.
+ * Calculates the indentation level of each comment in a comment thread.
+ *
+ * This function loops over an array representing a comment thread. For each
+ * comment, the function calculates the indentation level and saves it in the
+ * 'divs' property of the comment object.
*
* @param array $comments
- * An array of comment objects, keyed by cid.
- * @return
- * The $comments argument is altered by reference with indentation information.
+ * An array of comment objects, keyed by comment ID.
*/
function comment_prepare_thread(&$comments) {
// A flag stating if we are still searching for first new comment on the thread.
@@ -902,10 +928,10 @@ function comment_prepare_thread(&$comments) {
}
/**
- * Generate an array for rendering the given comment.
+ * Generates an array for rendering a comment.
*
* @param $comment
- * A comment object.
+ * The comment object.
* @param $node
* The node the comment is attached to.
* @param $view_mode
@@ -971,8 +997,8 @@ function comment_view($comment, $node, $view_mode = 'full', $langcode = NULL) {
/**
* Builds a structured array representing the comment's content.
*
- * The content built for the comment (field values, comments, file attachments or
- * other comment components) will vary depending on the $view_mode parameter.
+ * The content built for the comment (field values, comments, file attachments
+ * or other comment components) will vary depending on the $view_mode parameter.
*
* @param $comment
* A comment object.
@@ -1016,14 +1042,13 @@ function comment_build_content($comment, $node, $view_mode = 'full', $langcode =
}
/**
- * Helper function, build links for an individual comment.
- *
- * Adds reply, edit, delete etc. depending on the current user permissions.
+ * Adds reply, edit, delete, etc. links, depending on user permissions.
*
* @param $comment
* The comment object.
* @param $node
* The node the comment is attached to.
+ *
* @return
* A structured array of links.
*/
@@ -1078,7 +1103,7 @@ function comment_links($comment, $node) {
}
/**
- * Construct a drupal_render() style array from an array of loaded comments.
+ * Constructs render array from an array of loaded comments.
*
* @param $comments
* An array of comments as returned by comment_load_multiple().
@@ -1094,6 +1119,8 @@ function comment_links($comment, $node) {
*
* @return
* An array in the format expected by drupal_render().
+ *
+ * @see drupal_render()
*/
function comment_view_multiple($comments, $node, $view_mode = 'full', $weight = 0, $langcode = NULL) {
field_attach_prepare_view('comment', $comments, $view_mode, $langcode);
@@ -1421,6 +1448,7 @@ function comment_user_predelete($account) {
* recognized now.
* @param $comment
* The comment object.
+ *
* @return
* TRUE if the current user has acces to the comment, FALSE otherwise.
*/
@@ -1443,20 +1471,20 @@ function comment_save($comment) {
}
/**
- * Delete a comment and all its replies.
+ * Deletes a comment and all its replies.
*
* @param $cid
- * The comment to delete.
+ * The ID of the comment to delete.
*/
function comment_delete($cid) {
comment_delete_multiple(array($cid));
}
/**
- * Delete comments and all their replies.
+ * Deletes comments and all their replies.
*
* @param $cids
- * The comment to delete.
+ * The IDs of the comments to delete.
*
* @see hook_comment_predelete()
* @see hook_comment_delete()
@@ -1466,7 +1494,7 @@ function comment_delete_multiple($cids) {
}
/**
- * Load comments from the database.
+ * Loads comments from the database.
*
* @param $cids
* An array of comment IDs.
@@ -1483,20 +1511,20 @@ function comment_delete_multiple($cids) {
* @return
* An array of comment objects, indexed by comment ID.
*
+ * @todo Remove $conditions in Drupal 8.
+ *
* @see entity_load()
* @see EntityFieldQuery
- *
- * @todo Remove $conditions in Drupal 8.
*/
function comment_load_multiple($cids = array(), $conditions = array(), $reset = FALSE) {
return entity_load('comment', $cids, $conditions, $reset);
}
/**
- * Load the entire comment by cid.
+ * Loads the entire comment by comment ID.
*
* @param $cid
- * The identifying comment id.
+ * The ID of the comment to be loaded.
* @param $reset
* Whether to reset the internal static entity cache. Note that the static
* cache is disabled in comment_entity_info() by default.
@@ -1510,14 +1538,16 @@ function comment_load($cid, $reset = FALSE) {
}
/**
- * Get number of new comments for current user and specified node.
+ * Gets the number of new comments for the current user and the specified node.
*
* @param $nid
- * Node-id to count comments for.
+ * Node ID to count comments for.
* @param $timestamp
* Time to count from (defaults to time of last user access
* to node).
- * @return The result or FALSE on error.
+ *
+ * @return
+ * The number of new comments or FALSE if the user is not logged in.
*/
function comment_num_new($nid, $timestamp = 0) {
global $user;
@@ -1543,7 +1573,7 @@ function comment_num_new($nid, $timestamp = 0) {
}
/**
- * Get the display ordinal for a comment, starting from 0.
+ * Gets the display ordinal for a comment, starting from 0.
*
* Count the number of comments which appear before the comment we want to
* display, taking into account display settings and threading.
@@ -1552,8 +1582,10 @@ function comment_num_new($nid, $timestamp = 0) {
* The comment ID.
* @param $node_type
* The node type of the comment's parent.
+ *
* @return
* The display ordinal for the comment.
+ *
* @see comment_get_display_page()
*/
function comment_get_display_ordinal($cid, $node_type) {
@@ -1585,7 +1617,7 @@ function comment_get_display_ordinal($cid, $node_type) {
}
/**
- * Return the page number for a comment.
+ * Returns the page number for a comment.
*
* Finds the correct page number for a comment taking into account display
* and paging settings.
@@ -1594,6 +1626,7 @@ function comment_get_display_ordinal($cid, $node_type) {
* The comment ID.
* @param $node_type
* The node type the comment is attached to.
+ *
* @return
* The page number.
*/
@@ -1604,7 +1637,14 @@ function comment_get_display_page($cid, $node_type) {
}
/**
- * Page callback for comment editing.
+ * Page callback: Displays the comment editing form.
+ *
+ * Path: comment/%comment/edit
+ *
+ * @param $comment
+ * The comment object representing the comment to be edited.
+ *
+ * @see comment_menu()
*/
function comment_edit_page($comment) {
drupal_set_title(t('Edit comment %comment', array('%comment' => $comment->subject)), PASS_THROUGH);
@@ -1624,11 +1664,11 @@ function comment_forms() {
}
/**
- * Generate the basic commenting form, for appending to a node or display on a separate page.
+ * Form constructor for the basic commenting form.
*
* @see comment_form_validate()
* @see comment_form_submit()
- *
+ * @see comment_form_build_preview()
* @ingroup forms
*/
function comment_form($form, &$form_state, $comment) {
@@ -1823,7 +1863,7 @@ function comment_form($form, &$form_state, $comment) {
}
/**
- * Build a preview from submitted form values.
+ * Form submission handler for the 'preview' button in comment_form().
*/
function comment_form_build_preview($form, &$form_state) {
$comment = comment_form_submit_build_comment($form, $form_state);
@@ -1832,7 +1872,9 @@ function comment_form_build_preview($form, &$form_state) {
}
/**
- * Generate a comment preview.
+ * Generates a comment preview.
+ *
+ * @see comment_form_build_preview()
*/
function comment_preview($comment) {
global $user;
@@ -1886,7 +1928,9 @@ function comment_preview($comment) {
}
/**
- * Validate comment form submissions.
+ * Form validation handler for comment_form().
+ *
+ * @see comment_form_submit()
*/
function comment_form_validate($form, &$form_state) {
global $user;
@@ -1975,7 +2019,7 @@ function comment_submit($comment) {
}
/**
- * Updates the form state's comment entity by processing this submission's values.
+ * Updates the comment entity by processing the submission's values.
*
* This is the default builder function for the comment form. It is called
* during the "Save" and "Preview" submit handlers to retrieve the entity to
@@ -1984,6 +2028,8 @@ function comment_submit($comment) {
* before proceeding to the next step.
*
* @see comment_form()
+ * @see comment_form_preview()
+ * @see comment_form_submit()
*/
function comment_form_submit_build_comment($form, &$form_state) {
$comment = $form_state['comment'];
@@ -1993,7 +2039,10 @@ function comment_form_submit_build_comment($form, &$form_state) {
}
/**
- * Process comment form submissions; prepare the comment, store it, and set a redirection target.
+ * Form submission handler for comment_form().
+ *
+ * @see comment_form_validate()
+ * @see comment_form_submit_build_comment()
*/
function comment_form_submit($form, &$form_state) {
$node = node_load($form_state['values']['nid']);
@@ -2041,7 +2090,7 @@ function comment_form_submit($form, &$form_state) {
}
/**
- * Process variables for comment.tpl.php.
+ * Preprocesses variables for comment.tpl.php.
*
* @see comment.tpl.php
*/
@@ -2149,7 +2198,7 @@ function theme_comment_post_forbidden($variables) {
}
/**
- * Process variables for comment-wrapper.tpl.php.
+ * Preprocesses variables for comment-wrapper.tpl.php.
*
* @see comment-wrapper.tpl.php
* @see theme_comment_wrapper()
@@ -2163,10 +2212,10 @@ function template_preprocess_comment_wrapper(&$variables) {
}
/**
- * Return an array of viewing modes for comment listings.
+ * Returns an array of viewing modes for comment listings.
*
* We can't use a global variable array because the locale system
- * is not initialized yet when the comment module is loaded.
+ * is not initialized yet when the Comment module is loaded.
*/
function _comment_get_modes() {
return array(
@@ -2176,15 +2225,14 @@ function _comment_get_modes() {
}
/**
- * Return an array of "comments per page" settings from which the user
- * can choose.
+ * Returns an array of "comments per page" values that users can select from.
*/
function _comment_per_page() {
return drupal_map_assoc(array(10, 30, 50, 70, 90, 150, 200, 250, 300));
}
/**
- * Generate sorting code.
+ * Generates a sorting code.
*
* Consists of a leading character indicating length, followed by N digits
* with a numerical value in base 36 (alphadecimal). These codes can be sorted
@@ -2204,7 +2252,7 @@ function comment_int_to_alphadecimal($i = 0) {
}
/**
- * Decode sorting code back to an integer.
+ * Decodes a sorting code back to an integer.
*
* @see comment_int_to_alphadecimal()
*/
@@ -2213,7 +2261,7 @@ function comment_alphadecimal_to_int($c = '00') {
}
/**
- * Increment a sorting code to the next value.
+ * Increments a sorting code to the next value.
*
* @see comment_int_to_alphadecimal()
*/
@@ -2336,7 +2384,7 @@ function comment_unpublish_by_keyword_action($comment, $context) {
}
/**
- * Form builder; Prepare a form for blacklisted keywords.
+ * Form constructor for the blacklisted keywords form.
*
* @ingroup forms
* @see comment_unpublish_by_keyword_action()
@@ -2354,7 +2402,7 @@ function comment_unpublish_by_keyword_action_form($context) {
}
/**
- * Process comment_unpublish_by_keyword_action_form form submissions.
+ * Form submission handler for comment_unpublish_by_keyword_action_form().
*
* @see comment_unpublish_by_keyword_action()
*/
diff --git a/core/modules/comment/comment.pages.inc b/core/modules/comment/comment.pages.inc
index de8129de488e..5e3d9de40bd1 100644
--- a/core/modules/comment/comment.pages.inc
+++ b/core/modules/comment/comment.pages.inc
@@ -2,11 +2,12 @@
/**
* @file
- * User page callbacks for the comment module.
+ * User page callbacks for the Comment module.
*/
/**
- * This function is responsible for generating a comment reply form.
+ * Form constructor for the comment reply form.
+ *
* There are several cases that have to be handled, including:
* - replies to comments
* - replies to nodes
@@ -18,10 +19,9 @@
*
* @param $node
* Every comment belongs to a node. This is that node.
- *
* @param $pid
- * Some comments are replies to other comments. In those cases, $pid is the parent
- * comment's cid.
+ * (optional) Some comments are replies to other comments. In those cases,
+ * $pid is the parent comment's comment ID. Defaults to NULL.
*
* @return
* The rendered parent node or comment plus the new comment form.
@@ -100,10 +100,14 @@ function comment_reply($node, $pid = NULL) {
}
/**
- * Menu callback; publish specified comment.
+ * Page callback: Publishes the specified comment.
+ *
+ * Path: comment/%/approve
*
* @param $cid
* A comment identifier.
+ *
+ * @see comment_menu()
*/
function comment_approve($cid) {
if (!isset($_GET['token']) || !drupal_valid_token($_GET['token'], "comment/$cid/approve")) {
diff --git a/core/modules/comment/comment.test b/core/modules/comment/comment.test
index 2771bc46cdd8..3911a298a026 100644
--- a/core/modules/comment/comment.test
+++ b/core/modules/comment/comment.test
@@ -2,7 +2,7 @@
/**
* @file
- * Tests for comment.module.
+ * Tests for the Comment module.
*/
class CommentHelperCase extends DrupalWebTestCase {
@@ -19,7 +19,7 @@ class CommentHelperCase extends DrupalWebTestCase {
}
/**
- * Post comment.
+ * Posts a comment.
*
* @param $node
* Node to post comment on.
@@ -94,9 +94,13 @@ class CommentHelperCase extends DrupalWebTestCase {
/**
* Checks current page for specified comment.
*
- * @param object $comment Comment object.
- * @param boolean $reply The comment is a reply to another comment.
- * @return boolean Comment found.
+ * @param object $comment
+ * The comment object.
+ * @param boolean $reply
+ * Boolean indicating whether the comment is a reply to another comment.
+ *
+ * @return boolean
+ * Boolean indicating whether the comment was found.
*/
function commentExists($comment, $reply = FALSE) {
if ($comment && is_object($comment)) {
@@ -115,7 +119,7 @@ class CommentHelperCase extends DrupalWebTestCase {
}
/**
- * Delete comment.
+ * Deletes a comment.
*
* @param object $comment
* Comment to delete.
@@ -126,20 +130,20 @@ class CommentHelperCase extends DrupalWebTestCase {
}
/**
- * Set comment subject setting.
+ * Sets the value governing whether the subject field should be enabled.
*
* @param boolean $enabled
- * Subject value.
+ * Boolean specifying whether the subject field should be enabled.
*/
function setCommentSubject($enabled) {
$this->setCommentSettings('comment_subject_field', ($enabled ? '1' : '0'), 'Comment subject ' . ($enabled ? 'enabled' : 'disabled') . '.');
}
/**
- * Set comment preview setting.
+ * Sets the value governing the previewing mode for the comment form.
*
* @param int $mode
- * Preview value.
+ * The preview mode: DRUPAL_DISABLED, DRUPAL_OPTIONAL or DRUPAL_REQUIRED.
*/
function setCommentPreview($mode) {
switch ($mode) {
@@ -159,27 +163,31 @@ class CommentHelperCase extends DrupalWebTestCase {
}
/**
- * Set comment form location setting.
+ * Sets the value governing whether the comment form is on its own page.
*
* @param boolean $enabled
- * Form value.
+ * TRUE if the comment form should be displayed on the same page as the
+ * comments; FALSE if it should be displayed on its own page.
*/
function setCommentForm($enabled) {
$this->setCommentSettings('comment_form_location', ($enabled ? COMMENT_FORM_BELOW : COMMENT_FORM_SEPARATE_PAGE), 'Comment controls ' . ($enabled ? 'enabled' : 'disabled') . '.');
}
/**
- * Set comment anonymous level setting.
+ * Sets the value governing restrictions on anonymous comments.
*
* @param integer $level
- * Anonymous level.
+ * The level of the contact information allowed for anonymous comments:
+ * - 0: No contact information allowed.
+ * - 1: Contact information allowed but not required.
+ * - 2: Contact information required.
*/
function setCommentAnonymous($level) {
$this->setCommentSettings('comment_anonymous', $level, 'Anonymous commenting set to level ' . $level . '.');
}
/**
- * Set the default number of comments per page.
+ * Sets the value specifying the default number of comments per page.
*
* @param integer $comments
* Comments per page value.
@@ -189,7 +197,7 @@ class CommentHelperCase extends DrupalWebTestCase {
}
/**
- * Set comment setting for article content type.
+ * Sets a comment settings variable for the article content type.
*
* @param string $name
* Name of variable.
@@ -204,16 +212,17 @@ class CommentHelperCase extends DrupalWebTestCase {
}
/**
- * Check for contact info.
+ * Checks whether the commenter's contact information is displayed.
*
- * @return boolean Contact info is available.
+ * @return boolean
+ * Contact info is available.
*/
function commentContactInfoAvailable() {
return preg_match('/(input).*?(name="name").*?(input).*?(name="mail").*?(input).*?(name="homepage")/s', $this->drupalGetContent());
}
/**
- * Perform the specified operation on the specified comment.
+ * Performs the specified operation on the specified comment.
*
* @param object $comment
* Comment to perform operation on.
@@ -238,10 +247,11 @@ class CommentHelperCase extends DrupalWebTestCase {
}
/**
- * Get the comment ID for an unapproved comment.
+ * Gets the comment ID for an unapproved comment.
*
* @param string $subject
* Comment subject to find.
+ *
* @return integer
* Comment id.
*/
@@ -313,7 +323,7 @@ class CommentInterfaceTest extends CommentHelperCase {
}
/**
- * Test comment interface.
+ * Tests the comment interface.
*/
function testCommentInterface() {
$langcode = LANGUAGE_NONE;
@@ -735,7 +745,7 @@ class CommentInterfaceTest extends CommentHelperCase {
}
/**
- * Asserts that comment links appear according to the passed environment setup.
+ * Asserts that comment links appear according to the passed environment.
*
* @param $info
* An associative array describing the environment to pass to
@@ -831,7 +841,7 @@ class CommentInterfaceTest extends CommentHelperCase {
}
/**
- * Test previewing comments.
+ * Tests previewing comments.
*/
class CommentPreviewTest extends CommentHelperCase {
public static function getInfo() {
@@ -843,7 +853,7 @@ class CommentPreviewTest extends CommentHelperCase {
}
/**
- * Test comment preview.
+ * Tests comment preview.
*/
function testCommentPreview() {
$langcode = LANGUAGE_NONE;
@@ -874,7 +884,7 @@ class CommentPreviewTest extends CommentHelperCase {
}
/**
- * Test comment edit, preview, and save.
+ * Tests comment edit, preview, and save.
*/
function testCommentEditPreviewSave() {
$langcode = LANGUAGE_NONE;
@@ -938,7 +948,9 @@ class CommentPreviewTest extends CommentHelperCase {
}
}
-
+/**
+ * Tests anonymous commenting.
+ */
class CommentAnonymous extends CommentHelperCase {
public static function getInfo() {
return array(
@@ -954,7 +966,7 @@ class CommentAnonymous extends CommentHelperCase {
}
/**
- * Test anonymous comment functionality.
+ * Tests anonymous comment functionality.
*/
function testAnonymous() {
$this->drupalLogin($this->admin_user);
@@ -1092,7 +1104,7 @@ class CommentAnonymous extends CommentHelperCase {
}
/**
- * Verify pagination of comments.
+ * Verifies pagination of comments.
*/
class CommentPagerTest extends CommentHelperCase {
@@ -1105,7 +1117,7 @@ class CommentPagerTest extends CommentHelperCase {
}
/**
- * Confirm comment paging works correctly with flat and threaded comments.
+ * Confirms comment paging works correctly with flat and threaded comments.
*/
function testCommentPaging() {
$this->drupalLogin($this->admin_user);
@@ -1178,7 +1190,7 @@ class CommentPagerTest extends CommentHelperCase {
}
/**
- * Test comment ordering and threading.
+ * Tests comment ordering and threading.
*/
function testCommentOrderingThreading() {
$this->drupalLogin($this->admin_user);
@@ -1253,7 +1265,7 @@ class CommentPagerTest extends CommentHelperCase {
}
/**
- * Helper function: assert that the comments are displayed in the correct order.
+ * Asserts that the comments are displayed in the correct order.
*
* @param $comments
* And array of comments.
@@ -1278,7 +1290,7 @@ class CommentPagerTest extends CommentHelperCase {
}
/**
- * Test comment_new_page_count().
+ * Tests comment_new_page_count().
*/
function testCommentNewPageIndicator() {
$this->drupalLogin($this->admin_user);
@@ -1425,7 +1437,9 @@ class CommentNodeAccessTest extends CommentHelperCase {
$this->assertText($reply_subject);
}
}
-
+/**
+ * Tests comment approval functionality.
+ */
class CommentApprovalTest extends CommentHelperCase {
public static function getInfo() {
return array(
@@ -1505,7 +1519,7 @@ class CommentApprovalTest extends CommentHelperCase {
}
/**
- * Test comment approval functionality through node interface.
+ * Tests comment approval functionality through the node interface.
*/
function testApprovalNodeInterface() {
// Set anonymous comments to require approval.
@@ -1548,7 +1562,7 @@ class CommentApprovalTest extends CommentHelperCase {
}
/**
- * Functional tests for the comment module blocks.
+ * Tests the Comment module blocks.
*/
class CommentBlockFunctionalTest extends CommentHelperCase {
public static function getInfo() {
@@ -1560,7 +1574,7 @@ class CommentBlockFunctionalTest extends CommentHelperCase {
}
/**
- * Test the recent comments block.
+ * Tests the recent comments block.
*/
function testRecentCommentBlock() {
$this->drupalLogin($this->admin_user);
@@ -1643,7 +1657,7 @@ class CommentBlockFunctionalTest extends CommentHelperCase {
}
/**
- * Unit tests for comment module integration with RSS feeds.
+ * Unit tests for Comment module integration with RSS feeds.
*/
class CommentRSSUnitTest extends CommentHelperCase {
public static function getInfo() {
@@ -1655,7 +1669,7 @@ class CommentRSSUnitTest extends CommentHelperCase {
}
/**
- * Test comments as part of an RSS feed.
+ * Tests comments as part of an RSS feed.
*/
function testCommentRSS() {
// Find comment in RSS feed.
@@ -1675,7 +1689,7 @@ class CommentRSSUnitTest extends CommentHelperCase {
/**
- * Test to make sure comment content is rebuilt.
+ * Tests comment content rebuilding.
*/
class CommentContentRebuild extends CommentHelperCase {
public static function getInfo() {
@@ -1687,8 +1701,7 @@ class CommentContentRebuild extends CommentHelperCase {
}
/**
- * Test to ensure that the comment's content array is rebuilt for every
- * call to comment_view().
+ * Tests the rebuilding of comment's content arrays on calling comment_view().
*/
function testCommentRebuild() {
// Update the comment settings so preview isn't required.
@@ -1715,7 +1728,7 @@ class CommentContentRebuild extends CommentHelperCase {
}
/**
- * Test comment token replacement in strings.
+ * Tests comment token replacement in strings.
*/
class CommentTokenReplaceTestCase extends CommentHelperCase {
public static function getInfo() {
@@ -1815,7 +1828,7 @@ class CommentTokenReplaceTestCase extends CommentHelperCase {
}
/**
- * Test actions provided by the comment module.
+ * Tests actions provided by the Comment module.
*/
class CommentActionsTestCase extends CommentHelperCase {
public static function getInfo() {
@@ -1827,7 +1840,7 @@ class CommentActionsTestCase extends CommentHelperCase {
}
/**
- * Test comment publish and unpublish actions.
+ * Tests comment publish and unpublish actions.
*/
function testCommentPublishUnpublishActions() {
$this->drupalLogin($this->web_user);
@@ -1861,7 +1874,7 @@ class CommentActionsTestCase extends CommentHelperCase {
}
/**
- * Verify that a watchdog message has been entered.
+ * Verifies that a watchdog message has been entered.
*
* @param $watchdog_message
* The watchdog message.
@@ -1876,7 +1889,7 @@ class CommentActionsTestCase extends CommentHelperCase {
}
/**
- * Helper function: clear the watchdog.
+ * Clears watchdog.
*/
function clearWatchdog() {
db_truncate('watchdog')->execute();
@@ -1884,7 +1897,7 @@ class CommentActionsTestCase extends CommentHelperCase {
}
/**
- * Test fields on comments.
+ * Tests fields on comments.
*/
class CommentFieldsTest extends CommentHelperCase {
public static function getInfo() {
@@ -1929,7 +1942,7 @@ class CommentFieldsTest extends CommentHelperCase {
}
/**
- * Test that comment module works when enabled after a content module.
+ * Tests that comment module works when enabled after a content module.
*/
function testCommentEnable() {
// Create a user to do module administration.
@@ -1973,7 +1986,7 @@ class CommentFieldsTest extends CommentHelperCase {
}
/**
- * Test that comment module works correctly with plain text format.
+ * Tests that comment module works correctly with plain text format.
*/
function testCommentFormat() {
// Disable text processing for comments.
diff --git a/core/modules/comment/comment.tpl.php b/core/modules/comment/comment.tpl.php
index 8ba46d8464d8..678f79810fa9 100644
--- a/core/modules/comment/comment.tpl.php
+++ b/core/modules/comment/comment.tpl.php
@@ -6,8 +6,8 @@
*
* Available variables:
* - $author: Comment author. Can be link or plain text.
- * - $content: An array of comment items. Use render($content) to print them all, or
- * print a subset such as render($content['field_example']). Use
+ * - $content: An array of comment items. Use render($content) to print them
+ * all, or print a subset such as render($content['field_example']). Use
* hide($content['field_example']) to temporarily suppress the printing of a
* given element.
* - $created: Formatted date and time for when the comment was created.
@@ -27,13 +27,15 @@
* - $title: Linked title.
* - $classes: String of classes that can be used to style contextually through
* CSS. It can be manipulated through the variable $classes_array from
- * preprocess functions. The default values can be one or more of the following:
+ * preprocess functions. The default values can be one or more of the
+ * following:
* - comment: The current template type, i.e., "theming hook".
* - comment-by-anonymous: Comment by an unregistered user.
* - comment-by-node-author: Comment by the author of the parent node.
* - comment-preview: When previewing a new or edited comment.
* The following applies only to viewers who are registered users:
- * - comment-unpublished: An unpublished comment visible only to administrators.
+ * - comment-unpublished: An unpublished comment visible only to
+ * administrators.
* - comment-by-viewer: Comment by the user currently viewing the page.
* - comment-new: New comment since last the visit.
* - $title_prefix (array): An array containing additional output populated by
--
GitLab