WordPress.org

Make WordPress Core

Opened 8 years ago

Closed 7 years ago

Last modified 7 years ago

#25522 closed defect (bug) (fixed)

Hooks Docs: wp-includes/comment.php

Reported by: swissspidy Owned by: DrewAPicture
Milestone: 3.8 Priority: normal
Severity: normal Version:
Component: Inline Docs Keywords: has-patch commit
Focuses: Cc:

Description


Attachments (5)

25522.diff (16.0 KB) - added by swissspidy 8 years ago.
25522.2.diff (22.7 KB) - added by danieldudzic 7 years ago.
25522.3.diff (26.4 KB) - added by kpdesign 7 years ago.
Third pass
25522.4.diff (30.1 KB) - added by DrewAPicture 7 years ago.
4th pass
25522.5.diff (30.1 KB) - added by DrewAPicture 7 years ago.
Final tweaks

Download all attachments as: .zip

Change History (20)

@swissspidy
8 years ago

#1 @swissspidy
8 years ago

  • Keywords has-patch added; needs-patch removed

#2 follow-up: @swissspidy
8 years ago

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

#3 @DrewAPicture
8 years ago

  • Owner set to DrewAPicture
  • Status changed from new to reviewing

#4 in reply to: ↑ 2 @DrewAPicture
8 years ago

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 :)

#5 @DrewAPicture
7 years ago

  • Keywords needs-patch added; has-patch removed
  • Milestone changed from Awaiting Review to 3.8

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

#6 @kpdesign
7 years ago

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

@danieldudzic
7 years ago

#7 @danieldudzic
7 years ago

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.

#8 @danieldudzic
7 years ago

  • Cc danieldudzic added

@kpdesign
7 years ago

Third pass

#9 @kpdesign
7 years ago

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
7 years ago

4th pass

#10 @DrewAPicture
7 years ago

  • Keywords has-patch added; needs-patch removed

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
7 years ago

Final tweaks

#11 @DrewAPicture
7 years ago

  • Keywords commit added

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

Last edited 7 years ago by DrewAPicture (previous) (diff)

#12 @DrewAPicture
7 years ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

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.

#13 @SergeyBiryukov
7 years ago

In 26492:

Correct @since values. see #25522.

This ticket was mentioned in IRC in #wordpress-dev by DrewAPicture. View the logs.


7 years ago

#15 @DrewAPicture
7 years ago

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

Note: See TracTickets for help on using tickets.