Skip to content

GitLab

Commit 37f2b2f2 authored by catch's avatar catch
Browse files
Options

Issue #1332598 by sven.lauer: Clean up API docs for comment module.

parent 9f9744bf
Hide whitespace changes
Inline Side-by-side
Showing with 252 additions and 161 deletions
core/modules/comment/comment-node-form.js
View file @ 37f2b2f2
/**
* @file
* Attaches comment behaviors to the node form.
*/
(function ($) {
......
core/modules/comment/comment-wrapper.tpl.php
View file @ 37f2b2f2
......@@ -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
......
core/modules/comment/comment.admin.inc
View file @ 37f2b2f2
......@@ -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'];
......
core/modules/comment/comment.api.php
View file @ 37f2b2f2
......@@ -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)));
......
core/modules/comment/comment.install
View file @ 37f2b2f2
......@@ -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)) {
......
core/modules/comment/comment.module
View file @ 37f2b2f2
......@@ -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.
*