Skip to content
GitLab
Menu
Projects
Groups
Snippets
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Sign in
Toggle navigation
Menu
Open sidebar
project
drupal
Commits
37f2b2f2
Commit
37f2b2f2
authored
Jan 03, 2012
by
catch
Browse files
Issue
#1332598
by sven.lauer: Clean up API docs for comment module.
parent
9f9744bf
Changes
9
Hide whitespace changes
Inline
Side-by-side
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 p
rovide an HTML container for comments.
*
P
rovide
s
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
c
omment module.
* Admin page callbacks for the
C
omment 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
builde
r for the comment overview administration form.
* Form
constructo
r 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
* Execute
s
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 sav
ed.
*
Act on a
comment
being inserted or updat
ed.
*
* 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) {
}
/**
*
C
omments
are
being loaded from the database.
*
Act on c
omments 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
them
ing.
*
Act on a
comment
that
is being
assembled
before
render
ing.
*
* @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
c
omment module.
* Install, update and uninstall functions for the
C
omment module.
*/
/**
...
...
@@ -51,10 +51,10 @@ function comment_enable() {
/**
* Implements hook_modules_enabled().
*
* Creates comment body fields for node types existing before the
c
omment module
* Creates comment body fields for node types existing before the
C
omment 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
c
omment module in the loop of module_enable().
* both before and after
the C
omment 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
c
omment module is one of the modules being enabled.
// Only react if
the C
omment 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 c
omment 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
C
omment 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
c
omment module
* is enabled. For node types created before the
c
omment module is enabled,
* Creates a comment body field for a node type created while the
C
omment module
* is enabled. For node types created before the
C
omment 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.
* Find
s
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.
* Calculate
s 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.
* Build
s
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.
* Retrieve
s
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.
* Generate
s
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.
* Construct
s 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.
* Delete
s
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.
* Delete
s
comments and all their replies.
*
* @param $cids
* The comment to delete.
* The
IDs of the
comment
s
to delete.
*
* @see hook_comment_predelete()
* @see hook_comment_delete()
...
...
@@ -1466,7 +1494,7 @@ function comment_delete_multiple($cids) {
}
/**
* Load comments from the database.
* Load
s
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 c
id
.
* Load
s
the entire comment by c
omment ID
.
*
* @param $cid
* The
identifying comment i
d.
* The
ID of the comment to be loade
d.
* @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.
* Get
s 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.
* Get
s
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.
* Return
s
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.