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

WordPress Trac noreply at wordpress.org
Wed Sep 18 11:53:45 UTC 2013


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

 Replying to [comment:78 NikV]:
 > Replying to [comment:76 ericlewis]:
 > > attachment:post-thumbnail-template.php.diff - @NikV
 > >
 > > * All patches should be made from either the WP root directory (svn
 diff wp-includes/post-thumbnail-template.php > yourfile.diff), or trunk
 root (svn diff src/wp-includes/post-thumbnail-template.php >
 yourfile.diff)
 > > * Preferably name your patches the entire WP directory path to the
 file, and leave off the .php extension in the diff filename (so wp-
 includes/post-thumbnail-template.php would be wp-includes-post-thumbnail-
 template.diff)
 > > * Parameters such as $size here should use a @see reference to a
 function's docblock that describe in more detail the options for $size.
 For instance, this can accept either a string keyword for a size, or a
 two-item array representing width and height in pixels. Ideally we
 reference the a canonical doc so as not to repeat ourselves of the
 options.
 > > * "Begins to fetch the post thumbnail HTML" and "Stops fetching the
 post thumbnail HTML." would be better phrased as "Before fetching the post
 thumbnail HTML." and "After fetching the post thumbnail HTML." Actions are
 discrete points of execution, so using a verb like "begins" is misleading
 - the action is not ''doing'' anything.
 > > * "The ID of the post where the post thumbnail will be displayed." is
 confusing. Here let's be brief and say "Post ID." as it does in the
 function docblock for get_the_post_thumbnail().
 > > * s/iamge/image
 > > * "The ID of a post thumbnail." should be "The post thumbnail ID."
 We're not talking about a generic post thumbnail, it is a specific one
 that has been supplied. Ditto for "The size of a post thumbnail. "
 > > * Thanks for the work, look forward to the next draft!
 > How would I format the @see? Would I do it only for the $size?
 >
 Never mind. Patch will be submitted soon.

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


More information about the wp-trac mailing list