[wp-trac] [WordPress Trac] #23627: Allow plugins to short-circuit wp_nav_menu, good for performance

[WordPress Trac]

#23627: Allow plugins to short-circuit wp_nav_menu, good for performance
-------------------------+-----------------------
 Reporter:  kasparsd     |       Owner:
     Type:  enhancement  |      Status:  new
 Priority:  normal       |   Milestone:  3.9
Component:  Menus        |     Version:  3.5.1
 Severity:  normal       |  Resolution:
 Keywords:  has-patch    |     Focuses:  template
-------------------------+-----------------------

Comment (by DrewAPicture):

 Replying to [comment:10 kasparsd]:
 > Replying to [comment:9 nacin]:
 > > A few other things I'd suggest:
 >
 > Thanks for the suggestions, @nacin!
 >
 > I have added a modified patch. Not sure how to describe the default
 filter argument/value `null` in the PHPDoc.

 For the `null`, I usually try to just describe what the value basically
 is. And you can just use a docs-specific variable, maybe something like
 `$output`, e.g.:
 {{{
 * @param string|null $output Nav menu output to short-circuit with.
 Default null.
 }}}

 I've made that adjustment and others to the hook doc in
 [attachment:23627.diff].

 Notably, in the description I avoided describing **why** it's filterable,
 rather describing **what's** filterable. Typically we'll use a long
 description to outline the *why* or reasoning if it's unclear in the short
 description -- which I added in the patch.

 I also moved the `@see` tag out of an in-line parameter description.

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