[wp-trac] [WordPress Trac] #25588: Hook Docs: wp-includes/theme.php

[WordPress Trac]

#25588: Hook Docs: wp-includes/theme.php
--------------------------+---------------------------
 Reporter:  ShinichiN     |       Owner:  DrewAPicture
     Type:  defect (bug)  |      Status:  reviewing
 Priority:  normal        |   Milestone:  3.8
Component:  Inline Docs   |     Version:
 Severity:  normal        |  Resolution:
 Keywords:  needs-patch   |
--------------------------+---------------------------
Changes (by DrewAPicture):

 * keywords:  has-patch => needs-patch
 * type:  enhancement => defect (bug)
 * milestone:  Awaiting Review => 3.8


Comment:

 Hey, thanks for the patch. This is a really great start. Here are some
 notes on [attachment:25588.diff]:
 Overall:
 * Replace 'Filters' with 'Filter'
 * We can probably remove the abundant use of "The " at the beginning of
 most parameter descriptions. For instance, "The stylesheet directory URI"
 can become "Stylesheet directory URI"
 * Space out the specific action or filter lines per coding standards
 * Several parameter types are missing

 `template_directory_uri` filter:
 * Having the example URL for `$theme_root_url` is nice, but it might fit
 better in a long description for the filter

 `wp_cache_themes_persistently` filter:
 * Documentation for the second parameter is missing

 `theme_root_uri` filter:
 * Typo in the short description

 `switch_theme` filter:
 * The `$new_theme` parameter should have a type of `WP_Theme`

 `validate_current_theme` filter:
 * "Filter whether to validate '''the''' current theme."
 * There's no need to store the boolean value in a variable first. Just use
 a doc-specific variable in the parameter documentation. (if you're
 confused, we changed our approach to this a couple of weeks ago)
 * Specify the default boolean value for the parameter at the end of the
 description. Ex: Default true.

 `theme_mod_$name` filter:
 * Use a docs-specific variable in the parameter docs for the parameter.
 Maybe `$current_mod`
 * Use a long description to explain what the dynamic portion of the hook,
 `$name`, refers to

 The second use of the `theme_mod_$name` filter should be marked a
 duplicate as follows:
 {{{
 /** This filter is documented in wp-includes/theme.php */
 }}}

 `current_theme_supports-$feature` filter:
 * Maybe change the short description to something like "Filter whether the
 theme supports a specific feature
 * Use a long description to explain what the dynamic portion of the hook,
 `$feature`, refers to

 `after_switch_theme` action:
 * "Fires on the first WP load after '''a''' theme switch."
 * Since this action is fired multiple times and the second one will be
 marked as a duplicate, use a long description to describe the different
 contexts the action is used in, e.g. whether the old theme exists.

 The second use of the `after_switch_theme` action should be marked a
 duplicate as follows:
 {{{
 /** This action is documented in wp-includes/theme.php */
 }}}

--
Ticket URL: <http://core.trac.wordpress.org/ticket/25588#comment:2>
WordPress Trac <http://core.trac.wordpress.org/>
WordPress blogging software