[wp-trac] [WordPress Trac] #25621: Hook Docs: wp-includes/post-template.php

[WordPress Trac]

#25621: Hook Docs: wp-includes/post-template.php
-------------------------+------------------------------
 Reporter:  Toru         |       Owner:
     Type:  enhancement  |      Status:  new
 Priority:  normal       |   Milestone:  Awaiting Review
Component:  Inline Docs  |     Version:
 Severity:  normal       |  Resolution:
 Keywords:  has-patch    |
-------------------------+------------------------------

Comment (by 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 [http://make.wordpress.org/core/handbook
 /inline-documentation-standards/php-documentation-standards/ 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.

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