[wp-trac] [WordPress Trac] #29808: Post/paging navigation template tags

[WordPress Trac]

#29808: Post/paging navigation template tags
--------------------------------------------------+-----------------------
 Reporter:  obenland                              |       Owner:
     Type:  enhancement                           |      Status:  new
 Priority:  normal                                |   Milestone:  4.1
Component:  Themes                                |     Version:  trunk
 Severity:  normal                                |  Resolution:
 Keywords:  2nd-opinion twenty-fifteen has-patch  |     Focuses:  template
--------------------------------------------------+-----------------------
Changes (by DrewAPicture):

 * keywords:  2nd-opinion twenty-fifteen => 2nd-opinion twenty-fifteen has-
     patch


Comment:

 @obenland: Thanks for the more detailed docs in [attachment:29808.2.diff].
 Unfortunately, there's some work yet to do here to get it up to standard:

 Overall:
 * In basically all of the parameter and hash notation descriptions there
 needs to be a description of what values it accepts, and what is the
 default, in that order. If it's markup and stuff, just describe it, if you
 want to use the markup, surround it with backticks so it doesn't get
 parsed as something else. The syntax we prefer is "Description. Accepts x,
 y, or z. Default abc."
 * The 'Optional.' string, when used, should fall before the description,
 instead of after

 `get_the_pagination()`:
 * s/Url/URL
 * Any example you list out should be in backticks to ensure they don't get
 parsed as something else
 * All of the descriptions in the hash notation should line up from top to
 bottom, so everything from `$base` to `$add_args` needs to move over to
 align with the two at the bottom
 * See the above point about 'Accepts' and 'Default' missing from the hash
 notations

 `the_pagination()`:
 * Good news! You don't need to rehash (heh) the hash notation here since
 you're just referencing arguments already defined. Just use an inline
 `@see` reference on the `$args` param line. Maybe something like " {@see
 get_the_pagination()} for available arguments".

 `_navigation_markup()`:
 * See above about 'Optional.' preceding the description. And we don't need
 to mark arguments as  required, since everything is inferred to be
 required unless otherwise noted as optional.
 * 'Accepts' and 'Default' are missing from the parameter descriptions

--
Ticket URL: <https://core.trac.wordpress.org/ticket/29808#comment:8>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform