[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 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?

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