get_posts Some fields of the $args argument are not documented

[Marcio Zebedeu]

Some fields of the $args argument are not documented in get_posts.

I believe it is important to describe all the optional arguments for this function.

​https://developer.wordpress.org/reference/functions/get_posts/

[sebastienserre]

Hello Marcio and thank you for your ticket and contribution
There's already a menion to the WP Query documentation pages:
See WP_Query::parse_query() for all available arguments.
Too much doc should loose users I think

[Marcio Zebedeu]

Replying to sebastienserre:

Hello Marcio and thank you for your ticket and contribution
There's already a menion to the WP Query documentation pages:
See WP_Query::parse_query() for all available arguments.
Too much doc should loose users I think

I understand @sebastienserre

However, the WP_Query::parse_query has many parameters that are not used in the get_posts which can somehow confuse the user because not all arguments of the WP_Query::parse_query are really necessary to pass in get_posts

[SergeyBiryukov]

Hi there, welcome to WordPress Trac! Thanks for the ticket.

There was a previous discussion on this in comment:2:ticket:47896:

@birgire: The way I see it now, is that it's good if we can avoid duplicating the documentation of input arguments if possible and only document it if it's a part of the corresponding function's code base. Then e.g. refer to the other places where the other "hidden" but supported input arguments are documented.

and comment:8:ticket:47896:

@boonebgorges: I agree with this. I'd spell out the principle as follows:

1. If a function accepts arguments that are passed through, without modification, to another function, then those arguments should not be documented on the wrapper function, but there should be a reference along the lines of See get_terms() in the description of $args.
2. The wrapper function should fully document arguments that (a) are not passed through at all (such as $title_li) or (b) are modified or play a special role in the wrapper (such as $exclude_tree).

It was also previously discussed in #41058, specifically comment:8:ticket:41058.

[jorbin]

For the reasons that @SergeyBiryukov and @sebastienserre documentated above, I am closing this ticket as worksforme, the pointing to the called function rather than including duplicate documentation in the wrapper makes it easier to maintain while still solving the need to make sure arguments are documented.