Hook Docs (27): wp-includes/post-template.php

[Toru]

Attached patch has done for all hooks in wp-includes/post-template.php

[ericlewis]

Hi Toru,

thanks for the initial patch! Here are some comments:

• The long description should always come after the short description, before the @since tag. See the ​Inline Doc Standards for some examples of formatting.
• 'Filter the text which prepend the post title' should be 'Filter the text which prepends the post title'
• It would be helpful to say that protected_title_format and private_title_format only apply on the front-end.
• You have some extra spacing between the PHPDoc tags and their values (see the_title and get_the_guid in your patch)
• @param string $more_link_text Link text of the Read More link. is a bit verbose. How about @param string $more_link_text Read More link element.
• Filter the retrieved post excerpt can be Filter the post excerpt
• Filter the returned CSS classes for the current post can be Filter the CSS classes for the current post
• @param string $post->guid Global Unique Identifier (guid) of the post should be @param string $post_guid Global Unique Identifier (guid) of the post. This comes up a few times in your patch, so change them all please. Referencing class properties in PHPDoc is an issue, and we're going to be using pseudo-variables in the docblock where this happens.
• For hooks with multiple parameters, please pad type and short descriptions with spaces to align them into columns. See r25726 for an example.
• Parameter short descriptions should not contain articles, so @param int $post->ID The post ID. should be @param int $post->ID Post ID.
• Revisit short description of the_meta_key, looks like you were in the middle of it.
• Filter wp_list_pages. is too brief for a short description.
• Filters CSS classes applied to each list items of page list created by wp_list_pages(). is rough. Can you revisit and try to smooth that out?
• Filters a retrieved attachment page link needs a period on the end.
• Filters HTML output of attachment link with medium sized representation, wrapped with <p class="attachment"> attribute. is a bit verbose as well. Although the detail is a good thought, something more generic would suffice. Filter attachment markup to be prepended to post content., and then in the long description give more technical description,

Thanks again, looking forward to the next patch.

[DrewAPicture]

This still needs a new patch incorporating the changes suggested in comment:1.

[Toru]

Thank you very much ericlewis and DrewAPicture for the review. Took a time, but attached the 2nd patch at last.

[kpdesign]

Third pass

[kpdesign]

25621.3.diff​ contains fixes for language, formatting, and @since values.

This needs a secondary review and a recommendation.

[DrewAPicture]

Final pass

[DrewAPicture]

25621.diff​ should take care of it.

[DrewAPicture]

In 27676:

Inline documentation for hooks in wp-includes/post-template.php.

Props Toru and kpdesign.
Fixes #25621.