Make WordPress Core

Opened 10 years ago

Closed 10 years ago

#28680 closed defect (bug) (fixed)

Convert docs for default wp_link_pages() arguments to a hash notation

Reported by: drewapicture's profile DrewAPicture Owned by: drewapicture's profile DrewAPicture
Milestone: 4.0 Priority: normal
Severity: normal Version:
Component: Posts, Post Types Keywords: good-first-bug has-patch
Focuses: docs Cc:

Description

Default arguments for wp_link_pages() are already documented in the phpDoc, and they should be converted to the hash-notation style, as outlined in the inline docs standards.

Current Reference: http://developer.wordpress.org/reference/functions/wp_link_pages/

A good example of documenting arguments arrays is the phpDoc for wp_get_archives() in wp-includes/general-template.php.

Attachments (3)

28680.patch (3.7 KB) - added by taylorde 10 years ago.
Adds hash notation to wp_link_pages docblock
28680.2.patch (3.7 KB) - added by taylorde 10 years ago.
Documentation patch revision based on feedback. Adjusts language.
28680.3.patch (3.8 KB) - added by taylorde 10 years ago.
Upload the correct patch this time…

Download all attachments as: .zip

Change History (10)

#1 @DrewAPicture
10 years ago

  • Milestone changed from Awaiting Review to 4.0
  • Owner set to taylorde
  • Status changed from new to assigned

@taylorde
10 years ago

Adds hash notation to wp_link_pages docblock

#2 @taylorde
10 years ago

Also indicate that $echo, while it defaults to an integer, is evaluating a truthy condition and could, therefore, be expressed as a boolean.

#3 @DrewAPicture
10 years ago

  • Keywords has-patch added; needs-patch removed
  • Owner changed from taylorde to DrewAPicture
  • Status changed from assigned to reviewing

#4 @DrewAPicture
10 years ago

  • Keywords needs-patch added; has-patch removed

Hi, thanks for the patch.

Some notes:

  • On the $echo parameter, you can just use int|bool type (core style)
  • Anywhere possible, we try to reduce the use of "The" at the beginning of parameter descriptions. Just gets a little repetitive
  • All parameter descriptions should end with a period.
  • "To each bookmarks" is nonsensical
  • "Default is " can just be "Default empty" (except for the one that has an empty space in it.
  • Core style on values expected as int|bool, we notate that in the description as both just for clarity. So 1 would be 1|true, 0|false.

@taylorde
10 years ago

Documentation patch revision based on feedback. Adjusts language.

#5 @taylorde
10 years ago

  • Keywords has-patch added; needs-patch removed

Thanks for the feedback,
I've uploaded another patch that hopefully reflects what you're looking for a bit closer.

@taylorde
10 years ago

Upload the correct patch this time...

#6 @DrewAPicture
10 years ago

28680.3.patch looks great. Thanks!

#7 @DrewAPicture
10 years ago

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

In 28899:

Re-document default arguments in wp_link_pages() using the hash-notation style.

Props taylorde.
Fixes #28680.

Note: See TracTickets for help on using tickets.