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

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

parent 9f9744bf
/**
* @file
* Attaches comment behaviors to the node form.
*/
(function ($) { (function ($) {
......
...@@ -2,7 +2,7 @@ ...@@ -2,7 +2,7 @@
/** /**
* @file * @file
* Default theme implementation to provide an HTML container for comments. * Provides an HTML container for comments.
* *
* Available variables: * Available variables:
* - $content: The array of content-related elements for the node. Use * - $content: The array of content-related elements for the node. Use
......
...@@ -2,11 +2,20 @@ ...@@ -2,11 +2,20 @@
/** /**
* @file * @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') { function comment_admin($type = 'new') {
$edit = $_POST; $edit = $_POST;
...@@ -20,13 +29,13 @@ function comment_admin($type = 'new') { ...@@ -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 * @param $arg
* Current path's fourth component: the type of overview form ('approval' or * The type of overview form ('approval' or 'new').
* 'new').
* *
* @ingroup forms * @ingroup forms
* @see comment_admin()
* @see comment_admin_overview_validate() * @see comment_admin_overview_validate()
* @see comment_admin_overview_submit() * @see comment_admin_overview_submit()
* @see theme_comment_admin_overview() * @see theme_comment_admin_overview()
...@@ -140,7 +149,9 @@ function comment_admin_overview($form, &$form_state, $arg) { ...@@ -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) { function comment_admin_overview_validate($form, &$form_state) {
$form_state['values']['comments'] = array_diff($form_state['values']['comments'], array(0)); $form_state['values']['comments'] = array_diff($form_state['values']['comments'], array(0));
...@@ -151,10 +162,12 @@ function comment_admin_overview_validate($form, &$form_state) { ...@@ -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. * publishing, unpublishing or deleting.
*
* @see comment_admin_overview_validate()
*/ */
function comment_admin_overview_submit($form, &$form_state) { function comment_admin_overview_submit($form, &$form_state) {
$operation = $form_state['values']['operation']; $operation = $form_state['values']['operation'];
...@@ -182,13 +195,10 @@ function comment_admin_overview_submit($form, &$form_state) { ...@@ -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 * @ingroup forms
* @see comment_admin()
* @see comment_multiple_delete_confirm_submit() * @see comment_multiple_delete_confirm_submit()
*/ */
function comment_multiple_delete_confirm($form, &$form_state) { function comment_multiple_delete_confirm($form, &$form_state) {
...@@ -224,7 +234,7 @@ 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) { function comment_multiple_delete_confirm_submit($form, &$form_state) {
if ($form_state['values']['confirm']) { if ($form_state['values']['confirm']) {
...@@ -238,7 +248,15 @@ function comment_multiple_delete_confirm_submit($form, &$form_state) { ...@@ -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) { function comment_confirm_delete_page($cid) {
if ($comment = comment_load($cid)) { if ($comment = comment_load($cid)) {
...@@ -248,10 +266,15 @@ function comment_confirm_delete_page($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 * @ingroup forms
* @see comment_confirm_delete_page()
* @see comment_confirm_delete_submit() * @see comment_confirm_delete_submit()
* @see confirm_form()
*/ */
function comment_confirm_delete($form, &$form_state, $comment) { function comment_confirm_delete($form, &$form_state, $comment) {
$form['#comment'] = $comment; $form['#comment'] = $comment;
...@@ -268,7 +291,7 @@ function comment_confirm_delete($form, &$form_state, $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) { function comment_confirm_delete_submit($form, &$form_state) {
$comment = $form['#comment']; $comment = $form['#comment'];
......
...@@ -11,9 +11,10 @@ ...@@ -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 * @param $comment
* The comment object. * The comment object.
...@@ -24,7 +25,7 @@ function hook_comment_presave($comment) { ...@@ -24,7 +25,7 @@ function hook_comment_presave($comment) {
} }
/** /**
* The comment is being inserted. * Respond to creation of a new comment.
* *
* @param $comment * @param $comment
* The comment object. * The comment object.
...@@ -35,7 +36,7 @@ function hook_comment_insert($comment) { ...@@ -35,7 +36,7 @@ function hook_comment_insert($comment) {
} }
/** /**
* The comment is being updated. * Respond to updates to a comment.
* *
* @param $comment * @param $comment
* The comment object. * The comment object.
...@@ -46,7 +47,7 @@ function hook_comment_update($comment) { ...@@ -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 * @param $comments
* An array of comment objects indexed by cid. * An array of comment objects indexed by cid.
...@@ -59,7 +60,7 @@ function hook_comment_load($comments) { ...@@ -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 * @param $comment
* Passes in the comment the action is being performed on. * Passes in the comment the action is being performed on.
...@@ -76,16 +77,16 @@ function hook_comment_view($comment, $view_mode, $langcode) { ...@@ -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 * This hook is called after the content has been assembled in a structured
* and may be used for doing processing which requires that the complete comment * array and may be used for doing processing which requires that the complete
* content structure has been built. * comment content structure has been built.
* *
* If the module wishes to act on the rendered HTML of the comment rather than the * If the module wishes to act on the rendered HTML of the comment rather than
* structured content array, it may use this hook to add a #post_render callback. * the structured content array, it may use this hook to add a #post_render
* Alternatively, it could also implement hook_preprocess_comment(). See * callback. Alternatively, it could also implement hook_preprocess_comment().
* drupal_render() and theme() documentation respectively for details. * See drupal_render() and theme() documentation respectively for details.
* *
* @param $build * @param $build
* A renderable array representing the comment. * A renderable array representing the comment.
...@@ -105,24 +106,20 @@ function hook_comment_view_alter(&$build) { ...@@ -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 * @param $comment
* Passes in the comment the action is being performed on. * The comment the action is being performed on.
* @return
* Nothing.
*/ */
function hook_comment_publish($comment) { function hook_comment_publish($comment) {
drupal_set_message(t('Comment: @subject has been published', array('@subject' => $comment->subject))); 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 * @param $comment
* Passes in the comment the action is being performed on. * The comment the action is being performed on.
* @return
* Nothing.
*/ */
function hook_comment_unpublish($comment) { function hook_comment_unpublish($comment) {
drupal_set_message(t('Comment: @subject has been unpublished', array('@subject' => $comment->subject))); drupal_set_message(t('Comment: @subject has been unpublished', array('@subject' => $comment->subject)));
......
...@@ -2,7 +2,7 @@ ...@@ -2,7 +2,7 @@
/** /**
* @file * @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() { ...@@ -51,10 +51,10 @@ function comment_enable() {
/** /**
* Implements hook_modules_enabled(). * 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 * 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 * 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 * 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 * per-node-type customization of comment fields. Each one of these bundles
...@@ -65,7 +65,7 @@ function comment_enable() { ...@@ -65,7 +65,7 @@ function comment_enable() {
* @see comment_node_type_insert() * @see comment_node_type_insert()
*/ */
function comment_modules_enabled($modules) { 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 // hook_node_type_insert() is used to create body fields while the comment
// module is enabled. // module is enabled.
if (in_array('comment', $modules)) { if (in_array('comment', $modules)) {
......
...@@ -4,9 +4,9 @@ ...@@ -4,9 +4,9 @@
* @file * @file
* Enables users to comment on published content. * Enables users to comment on published content.
* *
* When enabled, the Drupal comment module creates a discussion * When enabled, the Comment module creates a discussion board for each Drupal
* board for each Drupal node. Users can post comments to discuss * node. Users can post comments to discuss a forum topic, story, collaborative
* a forum topic, story, collaborative book page, etc. * book page, etc.
*/ */
/** /**
...@@ -141,9 +141,19 @@ function comment_entity_info() { ...@@ -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) { function comment_node_type_load($name) {
if ($type = node_type_get_type(strtr($name, array('-' => '_')))) { if ($type = node_type_get_type(strtr($name, array('-' => '_')))) {
...@@ -318,8 +328,8 @@ function comment_count_unpublished() { ...@@ -318,8 +328,8 @@ function comment_count_unpublished() {
/** /**
* Implements hook_node_type_insert(). * Implements hook_node_type_insert().
* *
* Creates a comment body field for a node type created while the comment module * 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, * is enabled. For node types created before the Comment module is enabled,
* hook_modules_enabled() serves to create the body fields. * hook_modules_enabled() serves to create the body fields.
* *
* @see comment_modules_enabled() * @see comment_modules_enabled()
...@@ -358,6 +368,11 @@ function comment_node_type_delete($info) { ...@@ -358,6 +368,11 @@ function comment_node_type_delete($info) {
/** /**
* Creates a comment_body field instance for a given node type. * 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) { function _comment_body_field_create($info) {
// Create the field if needed. // Create the field if needed.
...@@ -473,6 +488,7 @@ function comment_block_view($delta = '') { ...@@ -473,6 +488,7 @@ function comment_block_view($delta = '') {
* *
* @param $cid * @param $cid
* A comment identifier. * A comment identifier.
*
* @return * @return
* The comment listing set to the page on which the comment appears. * The comment listing set to the page on which the comment appears.
*/ */
...@@ -494,7 +510,7 @@ function comment_permalink($cid) { ...@@ -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 * @param integer $number
* (optional) The maximum number of comments to find. Defaults to 10. * (optional) The maximum number of comments to find. Defaults to 10.
...@@ -523,7 +539,7 @@ function comment_get_recent($number = 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 * @param $num_comments
* Number of comments. * Number of comments.
...@@ -531,6 +547,7 @@ function comment_get_recent($number = 10) { ...@@ -531,6 +547,7 @@ function comment_get_recent($number = 10) {
* Number of new replies. * Number of new replies.
* @param $node * @param $node
* The first new comment node. * The first new comment node.
*
* @return * @return
* "page=X" if the page number is greater than zero; empty string otherwise. * "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) { ...@@ -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 * @ingroup themeable
*/ */
...@@ -714,10 +731,14 @@ function comment_node_view($node, $view_mode) { ...@@ -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 * @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) { function comment_node_page_additions($node) {
$additions = array(); $additions = array();
...@@ -756,7 +777,7 @@ function comment_node_page_additions($node) { ...@@ -756,7 +777,7 @@ function comment_node_page_additions($node) {
} }
/** /**
* Retrieve comments for a thread. * Retrieves comments for a thread.
* *
* @param $node * @param $node
* The node whose comment(s) needs rendering. * The node whose comment(s) needs rendering.
...@@ -765,6 +786,9 @@ function comment_node_page_additions($node) { ...@@ -765,6 +786,9 @@ function comment_node_page_additions($node) {
* @param $comments_per_page * @param $comments_per_page
* The amount of comments to display 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 * To display threaded comments in the correct order we keep a 'thread' field
* and order by that value. This field keeps this data in * and order by that value. This field keeps this data in
* a way which is easy to update and convenient to use. * a way which is easy to update and convenient to use.
...@@ -859,12 +883,14 @@ function comment_get_thread($node, $mode, $comments_per_page) { ...@@ -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 * @param array $comments
* An array of comment objects, keyed by cid. * An array of comment objects, keyed by comment ID.
* @return
* The $comments argument is altered by reference with indentation information.
*/ */
function comment_prepare_thread(&$comments) { function comment_prepare_thread(&$comments) {
// A flag stating if we are still searching for first new comment on the thread. // A flag stating if we are still searching for first new comment on the thread.
...@@ -902,10 +928,10 @@ function comment_prepare_thread(&$comments) { ...@@ -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 * @param $comment
* A comment object. * The comment object.
* @param $node * @param $node
* The node the comment is attached to. * The node the comment is attached to.
* @param $view_mode * @param $view_mode
...@@ -971,8 +997,8 @@ function comment_view($comment, $node, $view_mode = 'full', $langcode = NULL) { ...@@ -971,8 +997,8 @@ function comment_view($comment, $node, $view_mode = 'full', $langcode = NULL) {
/** /**
* Builds a structured array representing the comment's content. * Builds a structured array representing the comment's content.
* *
* The content built for the comment (field values, comments, file attachments or * The content built for the comment (field values, comments, file attachments
* other comment components) will vary depending on the $view_mode parameter. * or other comment components) will vary depending on the $view_mode parameter.
* *