[wp-trac] [WordPress Trac] #25522: Hooks Docs: wp-includes/comment.php

[WordPress Trac]

#25522: Hooks Docs: wp-includes/comment.php
--------------------------+---------------------------
 Reporter:  swissspidy    |       Owner:  DrewAPicture
     Type:  defect (bug)  |      Status:  reviewing
 Priority:  normal        |   Milestone:  3.8
Component:  Inline Docs   |     Version:
 Severity:  normal        |  Resolution:
 Keywords:  needs-patch   |
--------------------------+---------------------------
Changes (by DrewAPicture):

 * keywords:  has-patch => needs-patch
 * milestone:  Awaiting Review => 3.8


Comment:

 Hi, thanks for the patch. This is a pretty good start, just some things
 left to tweak.

 Notes on [attachment:25522.diff]:
 Overall:
 * Replace 'Filters' with 'Filter'
 * All short descriptions and parameter descriptions should end with a
 period
 * Space out the individual action or filter lines per coding standards

 `get_comment` action:
 * "Fires after getting the comment." is kind of a cop-out. Maybe something
 like "Fires after a comment is retrieved."

 `pre_get_comments` action:
 * "Fires before comments are retrieved"
 * The type on `&$this` is `WP_Comment_Query`, not array. When
 `do_action_ref_array()` or `apply_filters_ref_array()` are used, treat
 parameters as if they're passed directly

 `comments_clauses` filter:
 * "Filter the comment query clauses."
 * Same as `pre_get_comments`, `compact( $pieces )` and `&$this` are two
 separate parameters, so use their specific types

 `the_comments` filter:
 * "Filter the comment query results."
 * `$comments` and `&$this` are separate parameters with their own types

 `comment_cookie_lifetime` filter:
 * Use a docs-specific variable to represent the integer value. Maybe
 something like `$seconds`.

 `pre_comment_author_name` filter:
 * As this is a "pre_" filter, perhaps specify "before it is set" in the
 short description
 * Use a docs-specific variable to represent the parameter passed to the
 filter. Maybe `$author_cookie`

 `pre_comment_author_email` filter:
 * As this is a "pre_" filter, perhaps specify "before it is set" in the
 short description
 * Use a docs-specific variable to represent the parameter passed to the
 filter. Maybe `$author_email_cookie`

 `pre_comment_author_url` filter:
 * As this is a "pre_" filter, perhaps specify "before it is set" in the
 short description
 * Use a docs-specific variable to represent the parameter passed to the
 filter. Maybe `$author_url_cookie`

 `comment_duplicate_trigger` action:
 * "Comment data." for the parameter description

 `pre_comment_approved` filter:
 * As this is a "pre_" filter, perhaps specify "before it is set" in the
 short description
 * `$approved` the type should be `int|string`

 `comment_flood_filter` filter:
 * Use a docs-specific variable to represent the boolean parameter passed
 to the filter, maybe `$bool`

 `wp_count_comments` filter:
 * Use a docs-specific variable to represent the empty array passed to the
 filter, maybe `$count`

 `delete_comment` action:
 * "Fires before a comment is deleted."

 `wp_set_comment_status` action:
 * Use a docs-specific variable to represent the string passed to the
 action, maybe `$status`

 `trash_comment` action:
 * "Fires before a comment is sent to the trash."

 `trashed_comment` action:
 * "Fires after a comment is sent to the trash."

 `untrash_comment` action:
 * "Fires before a comment is restored from the trash."

 `untrashed_comment` action:
 * "Fires after a comment is restored from the trash."

 `unspam_comment` action:
 * "Fires before a comment is un-marked as Spam" (thoughts on this
 wording?)

 `unspammed_comment` action:
 * "Fires after a comment is un-marked as Spam" (thoughts on this as well?)

 `wp_insert_comment` action:
 * `$comment` is a Comment object

 `close_comments_for_post_types` filter:
 * Use a docs-specific variable to represent the array passed to the
 filter, maybe `$post_types`

 The second use of the `close_comments_for_post_types` should be marked as
 a duplicate with the following:
 {{{
 /** This filter is documented in wp-includes/comment.php */
 }}}

--
Ticket URL: <http://core.trac.wordpress.org/ticket/25522#comment:5>
WordPress Trac <http://core.trac.wordpress.org/>
WordPress blogging software