[wp-hackers] wp_list_pages meta conditionals

[Jeremy Clarke]

This is something to remember generally about the Codex: Any time it
lists arguments you pass in in the url query style ('x=y&z=a') there
is a fair likelihood that you can pass in more options than are
immediately obvious. In the codex's defense of course is the fact that
even after reading the function itself you can be left with a
overly-limited sense of what appropriate parameters are.

IMHO its a matter of ensuring that the phpDoc info gets across the
option cascade as clearly as possible. In the case of wp_list_pages we
can see the obvious culprit is a completely useless @param description
for its one argument:

 * @param array|string $args Optional. Override default arguments.

Sure it implies that you should just look down a few lines and read
the contents of $defaults, but even in that case it could be more
explicit and useful, something like "Overrides default arguments (see
$defaults array)". Really though it should probably hint at what the
defaults are and what they might do. Maybe those comments should go
inside the function just before the $defaults array is defined?

It should also have an @uses phpdoc definition to mention get_pages(),
anyone know if its appropriate to do something along the lines of

 * @uses get_pages() - extra query parameters not found in $defaults
can still be passed into this function and will be used by
get_pages().

I can't shake the feeling that the docs for functions like this (which
really have multiple params, having just one @param in the phpdoc is
borderline cheating when using this style of arguments) should have
each possible setting and its effect listed somewhere in the comments.
This would make it easier to read and the mere act of writing it up
would probably help the doc author to remember that they should
mention that other settings from the called function (in this case
get_pages ) can be used as well.


-- 
Jeremy Clarke
Code and Design | globalvoicesonline.org