WordPress.org

Make WordPress Core

Opened 6 years ago

Closed 6 years ago

#25621 closed defect (bug) (fixed)

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

Reported by: Toru Owned by: DrewAPicture
Milestone: 3.9 Priority: normal
Severity: normal Version:
Component: Posts, Post Types Keywords: has-patch commit
Focuses: docs, template Cc:
PR Number:

Description

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

Attachments (4)

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

Download all attachments as: .zip

Change History (13)

@Toru
6 years ago

#1 @ericlewis
6 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
6 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.

@Toru
6 years ago

#3 @Toru
6 years ago

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

#4 @DrewAPicture
6 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
6 years ago

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

#6 @nacin
6 years ago

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

@kpdesign
6 years ago

Third pass

#7 @kpdesign
6 years ago

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

This needs a secondary review and a recommendation.

@DrewAPicture
6 years ago

Final pass

#8 @DrewAPicture
6 years ago

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

25621.diff should take care of it.

#9 @DrewAPicture
6 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.