WordPress.org

Make WordPress Core

Opened 22 months ago

Closed 12 months ago

Last modified 10 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 22 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 14 months ago.
WP_Query only

Download all attachments as: .zip

Change History (19)

@DrewAPicture22 months ago

First-run for WP_Query, WP_Tax_Query, WP_Date_Query, WP_Meta_Query

comment:1 @DrewAPicture22 months ago

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

comment:2 @rmccue22 months ago

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

comment:3 @Viper007Bond21 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 @DrewAPicture21 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 @johnbillion21 months ago

Can we split this ticket into WP_Query and WP_Date_Query?

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

Opened #25552 for WP_Date_Query documentation.

comment:8 @DrewAPicture19 months ago

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

Sad punt face.

comment:9 @nacin17 months ago

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

comment:10 follow-up: @GaryJ15 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 @DrewAPicture15 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 @wonderboymusic14 months ago

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

@DrewAPicture14 months ago

WP_Query only

comment:13 @DrewAPicture14 months ago

  • Keywords needs-refresh needs-docs removed

25367.2.diff refreshes for WP_Query arguments only.

comment:14 @ircbot13 months ago

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

comment:15 @DrewAPicture12 months ago

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

comment:16 @DrewAPicture12 months ago

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

I think we're good here.

comment:17 @SergeyBiryukov10 months ago

In 29538:

Correct 'no_found_rows' parameter description.

see #25367.

Note: See TracTickets for help on using tickets.