Hooks Docs: wp-includes/comment.php

[swissspidy]

This is a big one. Would be great if someone has time to check it.

[DrewAPicture]

Replying to swissspidy:

This is a big one. Would be great if someone has time to check it.

Working up to it. We've seen quite the influx of hook docs tickets in the last two days, but we're starting to catch back up :)

[DrewAPicture]

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

Notes on 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 */

[kpdesign]

I'm working on an updated patch incorporating changes from ​comment:5.

[danieldudzic]

I have applied changes to 25522.diff following the suggestions from comment:5.

Regarding the wording of:

• "Fires before a comment is un-marked as Spam"

• "Fires after a comment is un-marked as Spam"

Can't think of anything better.

I would appreciate if someone could have a look, and see if I missed anything.

[kpdesign]

Third pass

[kpdesign]

25522.3.diff​ incorporates changes from ​comment:5, 25522.2.diff​, and provides docs for several missed hooks.

@todo: Complete doc blocks for the following hooks:

• transition_comment_status
• comment_{$old_status}_to_{$new_status}
• comment_{$new_status}_{$comment->comment_type}
• comment_post
• edit_comment
• pre_ping
• pingback_useragent

[DrewAPicture]

4th pass

[DrewAPicture]

25522.4.diff​ is a fourth (and I think final) pass. This is a big one, with 32 filters and 42 actions. I'll give it another once over and we should be good.

[DrewAPicture]

Final tweaks

[DrewAPicture]

A few tweaks in 25522.5.diff​. Let's do this thing.

[DrewAPicture]

In 26491:

Inline documentation for hooks in wp-includes/comment.php.

comment.php, a.k.a. "lots 'o hooks".

Props swissspidy for the initial patch. Props danieldudzic, kpdesign, and DrewAPicture.
Fixes #25522.

[SergeyBiryukov]

In 26492:

Correct @since values. see #25522.

[DrewAPicture]

Redundant do_action and apply_filters @uses tags were removed in [26867]. Forgot to link the ticket.