WordPress.org

Make WordPress Core

Opened 7 months ago

Last modified 4 days ago

#25367 assigned defect (bug)

Document WP_Query and related class arguments

Reported by: DrewAPicture Owned by: DrewAPicture
Milestone: Future Release Priority: normal
Severity: normal Version:
Component: Query Keywords: has-patch dev-feedback
Focuses: docs Cc:

Description

It's been a long time coming, but here we are.

We've never had a fully documented list of WP_Query and related class arguments in core docs, however, with the inline docs effort in full swing, and the Code Reference on the way, there's an increasing urgency to have this list in place.

And there's no better time to start than now.

Goals of this ticket:

  1. Document all accepted WP_Query arguments
  2. Document all related class arguments, including:
  • WP_Tax_Query arguments
  • WP_Date_Query arguments
  • WP_Meta_Query arguments

Goals of a future ticket:

  1. Remove duplicated WP_Query argument docs elsewhere in core inline docs.
  2. Back-reference mentions of accepting WP_Query parameters to the WP_Query docs

The attached patch is a relatively complete start to this effort.

Constructive input is welcome and encouraged for hashing out:

  1. What arguments should or shouldn't be documented
  2. Descriptions of said arguments in WP_Query or related classes
  3. Defaults and Accepted values for said arguments

Let's get to it.

Attachments (1)

25367.diff (18.8 KB) - added by DrewAPicture 7 months ago.
First-run for WP_Query, WP_Tax_Query, WP_Date_Query, WP_Meta_Query

Download all attachments as: .zip

Change History (12)

DrewAPicture7 months ago

First-run for WP_Query, WP_Tax_Query, WP_Date_Query, WP_Meta_Query

comment:1 DrewAPicture7 months ago

  • Owner set to DrewAPicture
  • Status changed from new to assigned

comment:2 rmccue7 months ago

+1, this is awesome and will save me a bunch of time documenting it for the REST API. <3

comment:3 Viper007Bond7 months ago

Awesome. Nice work!

Here's my feedback on the WP_Date_Query stuff:

  • If we're going to document the class via it's constructor, then it probably makes sense to remove a large portion of the PHPdoc that's at the top of the class. No need to duplicate.
  • Probably worth mentioning that the list of acceptable columns is filterable.
  • For before and after, if you're passing an array, then the month and day fields are optional (you don't have to supply all three). For before it defaults to January and/or the first day of the month and for after, it defaults to December and/or the last day of the month. This way you can just say "before 2013" or "before June 2013".
  • I think we can improve the wording for inclusive, but I'm not sure exactly how.
  • The "accepts" for $default_column is missing.

comment:4 DrewAPicture6 months ago

I think we're going to need a lot more eyes-on the WP_Query stuff before I'm happy enough to put it in. That said, I'd like to get the WP_Date_Query inline docs in for 3.7, then push the rest down the road.

comment:5 johnbillion6 months ago

Can we split this ticket into WP_Query and WP_Date_Query?

comment:6 DrewAPicture6 months ago

  • Milestone changed from 3.7 to 3.8

Moving to 3.8. Let's split out the WP_Date_Query docs as suggested by @johnbillion. I'll make a new ticket.

comment:7 DrewAPicture6 months ago

Opened #25552 for WP_Date_Query documentation.

comment:8 DrewAPicture5 months ago

  • Milestone changed from 3.8 to Future Release
  • Type changed from task (blessed) to defect (bug)

Sad punt face.

comment:9 nacin3 months ago

  • Component changed from Inline Docs to Query
  • Focuses docs added

comment:10 follow-up: GaryJ4 days ago

Patch needs updating to remove WP_Date_Query docs which have been committed via the other ticket.

Worth creating separate tickets for Taxonomy and Meta query docs, and getting them in, rather than trying to do it all under this ticket?

comment:11 in reply to: ↑ 10 DrewAPicture4 days ago

Replying to GaryJ:

Patch needs updating to remove WP_Date_Query docs which have been committed via the other ticket.

Worth creating separate tickets for Taxonomy and Meta query docs, and getting them in, rather than trying to do it all under this ticket?

That's fine, though I think I'd rather we/you/they wait to create each ticket until there's a patch to go with it.

Note: See TracTickets for help on using tickets.