Hook Docs: wp-includes/bookmark.php

[ShinichiN]

Inserting inline documents for all the hooks in wp-includes/bookmark.php

[DrewAPicture]

Hi, thanks for the patch. Some notes on 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

[ShinichiN]

Fixes the #25468 patch according to the review.

[ShinichiN]

Thank you for the review.

Is it ok to make change as below to the hooks?

before
apply_filters('get_bookmarks', $results, $r);

after
apply_filters( 'get_bookmarks', $results, $r );
just inserting spaces before and after the arguments.

[DrewAPicture]

Replying to ShinichiN:

Thank you for the review.

Is it ok to make change as below to the hooks?

before
apply_filters('get_bookmarks', $results, $r);

after
apply_filters( 'get_bookmarks', $results, $r );
just inserting spaces before and after the arguments.

Yep, sure is :)

[ShinichiN]

Added white spaces before/after the arguments of filters.

[kpdesign]

Second pass on 25468-3.diff

[DrewAPicture]

fixed duplicate tags

[DrewAPicture]

In 25934:

Inline documentation for hooks in wp-includes/bookmark.php.

Props ShinichiN, kpdesign.
Fixes #25468.

[dd32]

In 26046:

Add some missing braces to get_bookmarks() which was causing an early return. Introduced in [25934]. See #25468. Fixes #25874