WordPress.org

Make WordPress Core

Opened 7 months ago

Last modified 7 months ago

#49093 assigned defect (bug)

get_posts Some fields of the $args argument are not documented

Reported by: Marcio Zebedeu Owned by:
Milestone: Awaiting Review Priority: normal
Severity: minor Version: 5.4
Component: Posts, Post Types Keywords: close
Focuses: docs Cc:

Description

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/

Change History (4)

#1 follow-up: @sebastienserre
7 months ago

  • Keywords close added

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

#2 in reply to: ↑ 1 @Marcio Zebedeu
7 months ago

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

#3 @SergeyBiryukov
7 months ago

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.

Last edited 7 months ago by SergeyBiryukov (previous) (diff)

#4 @SergeyBiryukov
7 months ago

  • Component changed from General to Posts, Post Types
Note: See TracTickets for help on using tickets.