[wp-trac] [WordPress Trac] #25468: Hook Docs: wp-includes/bookmark.php

[WordPress Trac]

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

 * keywords:  has-patch => needs-patch
 * type:  enhancement => defect (bug)


Comment:

 Hi, thanks for the patch. Some notes on [attachment:25468.diff]:
 * Avoid making changes to functions and functional docs, especially
 whitespacing. Focus on the hooks :)

 `get_bookmarks` filter:
 * Since this is a "named" filter hook for a function, and used more than
 once, the main doc block should cover the various contexts it's evaluated
 in. So for the short description, maybe "Filter the returned list of
 bookmarks."
 * Use a long description (but not too long!) to describe the other
 contexts. For instance, the first instance of the filter returns the
 cached bookmarks list. The second returns a cached bookmarks list if the
 link category is passed but doesn't exist. The third returns the full
 cached results.
 * `$r` is an array of arguments passed to `get_bookmarks()` so just back-
 reference that, like this:
 {{{
 * @param array $r         An array of bookmark query arguments. @see
 get_bookmarks()
 }}}

 `edit_$field` filter:
 * Use the short description to describe _what's_ filterable.
 * Use a long description to describe what the `$field` portion of the
 dynamic hook name refers to.

 `pre_$field` filter:
 * Use a long description to describe what the `$field` portion of the
 dynamic hook name refers to.

 `$field` filter is a `//duplicate_hook`

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