WordPress.org

Make WordPress Core

Opened 18 months ago

Closed 8 months ago

Last modified 7 months ago

#25367 closed defect (bug) (fixed)

Document WP_Query and related class arguments

Reported by: DrewAPicture Owned by: DrewAPicture
Milestone: 4.0 Priority: normal
Severity: normal Version:
Component: Query Keywords: has-patch
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 (2)

25367.diff (18.8 KB) - added by DrewAPicture 18 months ago.
First-run for WP_Query, WP_Tax_Query, WP_Date_Query, WP_Meta_Query
25367.2.diff (8.3 KB) - added by DrewAPicture 10 months ago.
WP_Query only

Download all attachments as: .zip

Change History (19)

@DrewAPicture18 months ago

First-run for WP_Query, WP_Tax_Query, WP_Date_Query, WP_Meta_Query

comment:1 @DrewAPicture18 months ago

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

comment:2 @rmccue18 months ago

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

comment:3 @Viper007Bond18 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 @DrewAPicture17 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 @johnbillion17 months ago

Can we split this ticket into WP_Query and WP_Date_Query?

comment:6 @DrewAPicture17 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 @DrewAPicture17 months ago

Opened #25552 for WP_Date_Query documentation.

comment:8 @DrewAPicture15 months ago

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

Sad punt face.

comment:9 @nacin14 months ago

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

comment:10 follow-up: @GaryJ11 months 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 @DrewAPicture11 months 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.

comment:12 @wonderboymusic10 months ago

  • Keywords needs-refresh needs-docs added; dev-feedback removed
  • Milestone changed from Future Release to 4.0

@DrewAPicture10 months ago

WP_Query only

comment:13 @DrewAPicture10 months ago

  • Keywords needs-refresh needs-docs removed

25367.2.diff refreshes for WP_Query arguments only.

comment:14 @ircbot10 months ago

This ticket was mentioned in IRC in #wordpress-dev by DrewAPicture. View the logs.

comment:15 @DrewAPicture8 months ago

[28887] is a first run of the WP_Query args. Looks like it missed trac.

comment:16 @DrewAPicture8 months ago

  • Resolution set to fixed
  • Status changed from assigned to closed

I think we're good here.

comment:17 @SergeyBiryukov7 months ago

In 29538:

Correct 'no_found_rows' parameter description.

see #25367.

Note: See TracTickets for help on using tickets.