WordPress.org

Make WordPress Core

Opened 6 years ago

Closed 6 years ago

Last modified 6 years ago

#25662 closed defect (bug) (fixed)

Hook Docs: wp-admin/includes/class-wp-comments-list-table.php

Reported by: siobhyb Owned by: kpdesign
Milestone: 3.8 Priority: normal
Severity: normal Version:
Component: Inline Docs Keywords: has-patch commit
Focuses: Cc:
PR Number:

Description

Patch forthcoming.

Attachments (5)

class-wp-comments-list-table.patch (4.4 KB) - added by siobhyb 6 years ago.
First pass at wp-admin\includes\class-wp-comments-list-table.php.
class-wp-comments-list-table.2.patch (4.5 KB) - added by siobhyb 6 years ago.
Second pass at inline docs for wp-admin/includes/class-wp-comments-list-table.php. Including correct notation for duplicate hooks.
25662.patch (4.5 KB) - added by siobhyb 6 years ago.
Updated patch.
25662.2.patch (4.1 KB) - added by siobhyb 6 years ago.
Updated patch.
25662.3.patch (4.1 KB) - added by kpdesign 6 years ago.
Add var for admin_comment_types_dropdown param line

Download all attachments as: .zip

Change History (20)

@siobhyb
6 years ago

First pass at wp-admin\includes\class-wp-comments-list-table.php.

#1 follow-up: @siobhyb
6 years ago

I've attached my first pass at inline docs for wp-admin/includes/class-wp-comments-list-table.php and have added my notes below. :)

Actions:

  • restrict_manage_comments. Trac ticket where hook was first discussed and added: #21344.
  • manage_comments_nav. First added: [7018].
  • manage_comments_custom_column. Trac ticket where hook was first discussed and added: #9583.

Filters:

The documentation for the filters had already been completed by @drewapicture as part of his Filter of the Day project: http://fotd.werdswords.com/. The last two hooks are duplicates.

  • comment_edit_pre. Duplicate hook, was first-added to wp-admin/includes/comment.php.
  • comment_row_actions. Duplicate hook, was first-added to wp-admin/includes/dashboard.php.

I know the handling of duplicate hooks is being discussed in another ticket, I've used the "duplicate_hook" comment as I wasn't sure what approach to use. Let me know if this or anything else needs changing/improving. Thanks! :)

Last edited 6 years ago by SergeyBiryukov (previous) (diff)

#2 @siobhyb
6 years ago

  • Cc siobhanbamber@… added

#3 @siobhyb
6 years ago

  • Component changed from General to Inline Docs

#4 in reply to: ↑ 1 ; follow-up: @DrewAPicture
6 years ago

Replying to siobhyb:

I know the handling of duplicate hooks is being discussed in another ticket, I've used the "duplicate_hook" comment as I wasn't sure what approach to use. Let me know if this or anything else needs changing/improving. Thanks! :)

The style to use is:

/** This action|filter is documented in wp-admin/whatever.php */

@siobhyb
6 years ago

Second pass at inline docs for wp-admin/includes/class-wp-comments-list-table.php. Including correct notation for duplicate hooks.

#5 in reply to: ↑ 4 @siobhyb
6 years ago

Replying to DrewAPicture:

The style to use is:

/** This action|filter is documented in wp-admin/whatever.php */

Thanks! I've updated the patch accordingly.

#6 @DrewAPicture
6 years ago

  • Keywords has-patch added
  • Milestone changed from Awaiting Review to 3.8
  • Owner set to kpdesign
  • Status changed from new to reviewing

Thanks for the updated patch. We'll get back to you shortly with some notes.

#7 @kpdesign
6 years ago

@siobhyb: Thanks for the patch. :)

General:

  • Please make your patch from the root directory of your SVN checkout, not the folder the file is in. :)
  • Make sure there is a blank space before the * on each line after the opening /** so that the block lines up correctly. Like this:
/**
 * Short description.
 *
 * @since x.x.x
 *
 * @param ...
 */

comments_per_page:

  • Align the parameters and the descriptions.
  • Change "Default is 'All'" to "Default 'All'."

comment_status_links:

  • Remove long description.
  • Change @param description to "An array of fully-formed status links. Default 'All'. Accepts 'All', 'Pending', 'Approved', 'Spam', and 'Trash'." Break the line before "Accepts...", and then align it with the description.

admin_comment_types_dropdown:

  • s/drop down/dropdown in short description.
  • Remove long description.
  • Change @param to: "@param array $comment_types An array of comment types. Accepts 'Comments', 'Pings'."

restrict_manage_comments:

  • Change short description to "Fires just before the Filter submit button for comment types."
  • Remove long description.

manage_comments_nav:

  • Change short description to "Fires after the Filter submit button for comment types."
  • Remove long description.

manage_comments_custom_column:

  • Short description should be "Fires when the default column output is displayed for a single row."
  • Remove long description.
  • Align the parameters and the descriptions, use spaces please.

Could you make these changes, and submit a new patch please? :)

#8 follow-up: @siobhyb
6 years ago

@kpdesign: I've updated the patch as requested.

Please make your patch from the root directory of your SVN checkout, not the folder the file is in. :)

Can you let me know if I've done this correctly this time? Thanks. :)

@siobhyb
6 years ago

Updated patch.

#9 in reply to: ↑ 8 @kpdesign
6 years ago

@siobhyb: Thanks for updating the patch. :)

Just a few small things to fix:

I noticed you edited lines 314-315, but there's no filter there. Could you remove that edit please?

comments_per_page:

  • Remove extra whitespace at the end of each line in the doc block.

comment_status_links:

  • Remove extra whitespace at the end of the first @param line.

comment_edit_pre:

  • Remove <?php echo after opening <textarea class=...> tag (same line).
  • Change esc_textarea( apply_filters( 'comment_edit_pre', $comment->comment_content ) ); to echo esc_textarea( apply_filters( 'comment_edit_pre', $comment->comment_content ) );.

It should look like this:

	<textarea class="comment" rows="1" cols="1">
		<?php
		/** This filter is documented in wp-admin/includes/comment.php */
		echo esc_textarea( apply_filters( 'comment_edit_pre', $comment->comment_content ) );
		?>
	</textarea>

manage_comments_custom_column:

  • Second @param line, only one space between the $var and the description, then align the description on the first @param line to match the description on the second line.

Can you let me know if I've done this correctly this time? Thanks. :)

Yes, you did. The latest patch is from the root directory. :)

#10 @kpdesign
6 years ago

  • Keywords needs-patch added; has-patch removed

#11 @siobhyb
6 years ago

I noticed you edited lines 314-315, but there's no filter there. Could you remove that edit please?

Genuinely didn't realise I'd done that! So glad you noticed. :)

I've completed all the changes you set out and updated the patch.

@siobhyb
6 years ago

Updated patch.

@kpdesign
6 years ago

Add var for admin_comment_types_dropdown param line

#12 @kpdesign
6 years ago

  • Keywords has-patch commit added; needs-patch removed

25662.3.patch looks good. Ready for commit.

#13 @SergeyBiryukov
6 years ago

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

In 26138:

Inline documentation for hooks in wp-admin/includes/class-wp-comments-list-table.php.

props siobhyb, kpdesign.
fixes #25662.

#14 @nacin
6 years ago

In 26273:

Remove whitespace from the inside of a <textarea> element, added in [26138] with inline documentation.

see #25662.

#15 @nacin
6 years ago

[26273] is an interesting little side effect — sometimes, whitespace matters. Just something to keep in the back of your mind!

Note: See TracTickets for help on using tickets.