Hook Docs (14): wp-admin/includes/screen.php

[enej]

Attached patch has doc for filters and action found in the file wp-admin/includes/screen.php

[enej]

Hook docs for file wp-admin/includes/screen.php

[DrewAPicture]

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

[enej]

Thank you so much Drew, for your feedback. I will try to update this patch later this week.

[enej]

Second pass at screen.php file

[kpdesign]

Third pass

[kpdesign]

26821.3.diff​ contains language and formatting changes, and fixes for duplicate hooks.

This needs a secondary review and a recommendation.

[enej]

26821.3.diff reads way better. Thank you Kim!

The only thing that I found is manage_$screen->id_columns filter was around since 2.7.0 see ​http://svn.automattic.com/wordpress/tags/2.7/wp-admin/includes/template.php line 841.

Instead of $screen->id WordPress used $page.

[DrewAPicture]

Final pass

[DrewAPicture]

In 27256:

Inline documentation for hooks in wp-admin/includes/screen.php.

Props enej, kpdesign.
Fixes #26821.