Make WordPress Core

Opened 11 years ago

Closed 10 years ago

#25621 closed defect (bug) (fixed)

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

Reported by: toru's profile Toru Owned by: drewapicture's profile DrewAPicture
Milestone: 3.9 Priority: normal
Severity: normal Version:
Component: Posts, Post Types Keywords: has-patch commit
Focuses: docs, template Cc:


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

Attachments (4)

post-template.diff (12.3 KB) - added by Toru 11 years ago.
post-template.2.diff (13.7 KB) - added by Toru 10 years ago.
25621.3.diff (12.2 KB) - added by kpdesign 10 years ago.
Third pass
25621.diff (12.6 KB) - added by DrewAPicture 10 years ago.
Final pass

Download all attachments as: .zip

Change History (13)

11 years ago

#1 @ericlewis
11 years ago

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.

#2 @DrewAPicture
10 years ago

  • Keywords needs-patch added; has-patch removed
  • Owner set to DrewAPicture
  • Status changed from new to reviewing
  • Type changed from enhancement to defect (bug)

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

#3 @Toru
10 years ago

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

#4 @DrewAPicture
10 years ago

  • Keywords has-patch added; needs-patch removed
  • Summary changed from Hook Docs: wp-includes/post-template.php to Hook Docs (27): wp-includes/post-template.php

#5 @jeremyfelt
10 years ago

  • Component changed from Inline Docs to Template
  • Focuses docs added

#6 @nacin
10 years ago

  • Component changed from Template to Posts, Post Types
  • Focuses template added

10 years ago

Third pass

#7 @kpdesign
10 years ago

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

This needs a secondary review and a recommendation.

10 years ago

Final pass

#8 @DrewAPicture
10 years ago

  • Keywords commit added
  • Milestone changed from Awaiting Review to 3.9

25621.diff should take care of it.

#9 @DrewAPicture
10 years ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

In 27676:

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

Props Toru and kpdesign.
Fixes #25621.

Note: See TracTickets for help on using tickets.