[wp-trac] [WordPress Trac] #26821: Hook Docs (14): wp-admin/includes/screen.php

[WordPress Trac]

#26821: Hook Docs (14): wp-admin/includes/screen.php
----------------------------+------------------------------
 Reporter:  enej            |       Owner:  kpdesign
     Type:  defect (bug)    |      Status:  assigned
 Priority:  normal          |   Milestone:  Awaiting Review
Component:  Bootstrap/Load  |     Version:
 Severity:  normal          |  Resolution:
 Keywords:  needs-patch     |     Focuses:  docs
----------------------------+------------------------------
Changes (by DrewAPicture):

 * keywords:  has-patch => needs-patch


Comment:

 Hi, thanks for the patch. Here some feedback for the next round of
 changes:

 Overall:
 * All descriptions should start with a capital letter, and end with a
 period. The same goes for parameter descriptions.
 * All `@since` versions should follow the 3-digit x.x.x style
 * Remove the functional docs changes on the show_screen_option() method.
 If you'd like to patch these changes and submit them in a different
 ticket, we can review those improvements separately. For now, those
 changes should be removed from the patch here :)

 `manage_$screen->id_columns` filter:
 * Change the description to "Filter the column headers for a list table on
 a specific screen."
 * As this is a "dynamic" hook, we need to outline what the dynamic
 portion, e.g. `$screen->id` represents in a long description.
 * We should be using a docs-specific variable for the single parameter
 here. I suggest something like `$columns`

 `default_hidden_meta_boxes` filter:
 * As part of the suggested language for filters and actions, you should
 use 'Filter X', rather than 'Filters X'. The filter itself doesn't filter
 anything :)
 * Parameter descriptions should start with a capital letter and end with a
 period.

 `hidden_meta_boxes` filter:
 * 'Filter' instead of 'Filters' in the description
 * Parameter descriptions should start with a capital letter and end with a
 period.

 `current_screen` hook:
 * "Fires after the current screen has been set."
 * Needs a period at the end of the parameter description.

 `contextual_help_list`, `contextual_help`, and `default_contextual_help`
 filters:
 * Should probably use an `@deprecated` tag here for 3.3.0 and point out
 which hook or method should be used instead.
 * Parameter descriptions, variables, and formatting are missing.

 `screen_layout_columns` filter:
 * The "`// Back compat for plugins using the filter instead of
 add_screen_option()` comment should be moved and incorporated into the
 long description for this filter's docs.
 * 'Filter' instead of 'Filters' in the description.
 * Parameter descriptions, variables, and formatting are missing.

 `screen_settings` filter:
 * 'Filter' instead of 'Filters'.
 * What are "screen settings"? Can you be more descriptive here?
 * Parameter descriptions, variables, and formatting are missing.

 `screen_options_show_screen` filter:
 * Replace 'weather' with 'whether'.
 * Parameter descriptions, variables, and formatting are missing.

 `comments_per_page`, `edit_categories_per_page`, `edit_posts_per_page`
 filters:
 * You need to be specific about which per page setting each filter is
 addressing. Are these in admin screen only, only for specific object
 types?
 * Parameter descriptions should start with a capital letter and end with a
 period.

 `$option` filter:
 * You can mark this as a duplicate with:
 {{{
 /** This filter is documented in wp-admin/includes/class-wp-list-table.php
 */
 }}}

 That should be good for round one. Looking forward to round two :)

--
Ticket URL: <https://core.trac.wordpress.org/ticket/26821#comment:4>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform