Make WordPress Core

Opened 10 years ago

Closed 10 years ago

Last modified 10 years ago

#25367 closed defect (bug) (fixed)

Document WP_Query and related class arguments

Reported by: drewapicture's profile DrewAPicture Owned by: drewapicture's profile 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 10 years 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 years ago.
WP_Query only

Download all attachments as: .zip

Change History (19)

@DrewAPicture
10 years ago

First-run for WP_Query, WP_Tax_Query, WP_Date_Query, WP_Meta_Query

#1 @DrewAPicture
10 years ago

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

#2 @rmccue
10 years ago

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

#3 @Viper007Bond
10 years 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.

#4 @DrewAPicture
10 years 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.

#5 @johnbillion
10 years ago

Can we split this ticket into WP_Query and WP_Date_Query?

#6 @DrewAPicture
10 years 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.

#7 @DrewAPicture
10 years ago

Opened #25552 for WP_Date_Query documentation.

#8 @DrewAPicture
10 years ago

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

Sad punt face.

#9 @nacin
10 years ago

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

#10 follow-up: @GaryJ
10 years 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?

#11 in reply to: ↑ 10 @DrewAPicture
10 years 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.

#12 @wonderboymusic
10 years ago

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

@DrewAPicture
10 years ago

WP_Query only

#13 @DrewAPicture
10 years ago

  • Keywords needs-refresh needs-docs removed

25367.2.diff refreshes for WP_Query arguments only.

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


10 years ago

#15 @DrewAPicture
10 years ago

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

#16 @DrewAPicture
10 years ago

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

I think we're good here.

#17 @SergeyBiryukov
10 years ago

In 29538:

Correct 'no_found_rows' parameter description.

see #25367.

Note: See TracTickets for help on using tickets.