[wp-trac] [WordPress Trac] #25229: Add Inline Docs for Hooks

[WordPress Trac]

#25229: Add Inline Docs for Hooks
----------------------------+------------------
 Reporter:  rzen            |       Owner:
     Type:  task (blessed)  |      Status:  new
 Priority:  normal          |   Milestone:  3.7
Component:  Inline Docs     |     Version:
 Severity:  normal          |  Resolution:
 Keywords:                  |
----------------------------+------------------

Comment (by DrewAPicture):

 '''Weekly Triage/Recap – Sept. 11''

 After yesterdays weekly inline-docs chat, we decided to start doing a
 weekly triage of patches on this ticket to both:
 * Ensure submitters get feedback on remaining patches
 * Committers know what's ready to go in

 '''Patches committed'''
 ||=  Patch  =||=  File  =||=  Changeset  =||
 ||[attachment:wp-comments-post.diff]||wp-comments-post.php||[25249],
 [25251]||
 ||[attachment:admin-footer.diff]||wp-admin/admin-footer.php||[25252]||
 ||[attachment:index.diff]||wp-admin/index.php||[25250]||
 ||[attachment:wp-trackback.diff]||wp-trackback||[25253]||
 ||[attachment:xmlrpc.diff]||xmlrpc.php||[25281]||
 ||[attachment:wp-comment.diff]||wp-admin/comment.php||[25282]||
 ||[attachment:custom-background.diff]||wp-admin/custom-
 background.php||[25283]||
 ||[attachment:wp-db.diff]||wp-includes/wp-db.php||[25284]||
 ||[attachment:rss.diff]||wp-includes/rss.php||[25286]||
 ||[attachment:http.php.4.diff]||wp-includes/http.php||[25302]||
 ||[attachment:options.patch]​||wp-admin/options.php||[25372]||

 Contributions by: rzen, natejacobs, bananastalktome, nacin, bftrick,
 dustyf, tw2113, siobhyb

 '''Patches in review'''
 [attachment:author-template.patch] for wp-includes/author-template.php —
 @Frank Klein
 * The functional docs changes should be split out and submitted with a
 separate Inline Docs ticket. Once that's done and you've resubmitted just
 the hooks docs, it should be ready to go in.

 [attachment:ms.diff] for wp-admin/includes/ms.php — @enej
 * `@since` tags should use the three-digit x.x.x style.
 * For the `new_admin_email_content` and `new_user_email_content` filters,
 I'd suggest pullout the email text string into a variable before the
 filter doc blocks, then referencing that directly in the `@param` lines
 * For short descriptions, focus more on '''what's''' being filtered, not
 ''why''.
 {{{
 // For instance, this:
 "Allows you to modify the tables that you want to be dropped when the blog
 is deleted."

 //should be more like:
 "Filter the tables to drop when a blog is deleted."

 //This:
 "Allows you to modify the upload base directory that is going to be
 deleted when the blog is deleted."

 // should be more like:
 "Filter the upload base directory to be deleted when a blog is deleted."
 }}}

 [attachment:wp-activate.diff] for wp-activate.php — @nullvariable
 * Remove the action long descriptions as they are unnecessary and
 redundant.
 * @since versions should be in the x.x.x 3-digit style
 * Remove the functional doc changes, just focus on the actions here :)
 * Side note: @MU shouldn't ever be changed since it signifies that the
 function came from WPMU

 [attachment:ms-delete-site.php.diff] for wp-admin/ms-delete-site.php —
 @NikV
 * There should be a single space after asterisks (*) in doc blocks, except
 for the closing `*/`
 * Your short description should describe what value is being filtered, not
 what will be done with it, if that makes sense. See the gist I linked
 below for an example.
 * Capitalize Unknown
 * I'd maybe suggest splitting the string content out to a variable before
 the doc block starts, so when you do the `@param` line, you can just
 reference the variable directly. Something like this:
 https://gist.github.com/DrewAPicture/6541914

 [attachment:admin-ajax.diff] for wp-admin/admin-ajax.php — @nullvariable
 * Just `//duplicate_hook` will suffice for the `admin_init` hook
 * Short descriptions should start a capital letter and end with a period.
 * Add a blank link between the long description and the `@link`
 * `@since` should use the 3-digit x.x.x style

 [attachment:shortcodes.diff]​ for wp-includes/shortcodes.php — @natejacobs
 * Looks a lot better. Last little tweak is that parameter short
 descriptions should start with a capital letter. Once that's done, it'll
 be ready to go in.

 '''Patches ready for commit'''
 ||=  Patch  =||=  File  =||=  Props  =||=  Notes  =||
 ||[attachment:options-writing.patch]​||wp-admin/options-
 writing.php||siobhyb||||
 ||[attachment:nav-menu-template.2.diff]||wp-includes/nav-menu-
 template.php||Faison||Please add a period to the short description for the
 `wp_nav_menu` filter||

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