Make WordPress Core

Opened 7 years ago

Closed 7 years ago

#29846 closed defect (bug) (fixed)

Document default arguments for WP_User_Query::prepare_query()

Reported by: DrewAPicture Owned by: tschutter
Milestone: 4.1 Priority: normal
Severity: normal Version:
Component: Users Keywords: good-first-bug has-patch
Focuses: docs Cc:

Description (last modified by DrewAPicture)

The default arguments for WP_User_Query need to be documented in the hash notation style. The actual docs would go into the docblock for the WP_User_Query::prepare_query() method.

For a good example of documenting default arguments in a hash notation, check out the docs for WP_Query::parse_query().

If it helps, you can use the WP_User_Query Codex article to find more information on the default arguments.

This ticket is reserved for new contributors on the good-first-bug keyword.

Attachments (4)

doc-wp-user-query-args.29846.diff (2.9 KB) - added by tschutter 7 years ago.
Adds inline documentation for default arguments WP_User_Query::prepare_query()
doc-wp-user-query-args.29846.1.diff (3.2 KB) - added by tschutter 7 years ago.
29846.diff (3.5 KB) - added by DrewAPicture 7 years ago.
wrapping
doc-wp-user-query-args.29846.2.diff (3.6 KB) - added by tschutter 7 years ago.

Download all attachments as: .zip

Change History (16)

#1 @DrewAPicture
7 years ago

  • Description modified (diff)

#2 @tschutter
7 years ago

I will be working on this, if that's okay.

@tschutter
7 years ago

Adds inline documentation for default arguments WP_User_Query::prepare_query()

#3 @tschutter
7 years ago

  • Keywords has-patch added; needs-patch removed

doc-wp-user-query-args.29846.diff adds inline documentation to WP_User_Query::prepare_query().

#4 @DrewAPicture
7 years ago

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

#5 @DrewAPicture
7 years ago

  • Keywords needs-patch added; has-patch removed
  • Milestone changed from Awaiting Review to 4.1

Hi Tobias, thanks for the patch. doc-wp-user-query-args.29846.diff is a really great start!

Just a few things:

  • We need to include the default values at the end of each argument description
  • Descriptions should extend about 80-120 characters per line, beyond that, wrap to the next line and space-align the subsequent lines with the first letter of the description
  • $meta_compare Need to list what values are accepted
  • $include|exclude - Both specifically accept an array of user IDs, so you should specify that
  • $search - The focus should be on what the value is more so than what it does. So for instance, start with what $search is, followed by its significance
  • $orderby - When you're referencing other arguments in a description, use the $-type value instead of in single quotes, e.g. $meta_key vs 'meta_key'
  • $count_total - Probably worth mentioning that if pagination isn't needed, setting this to false can improve performance
Last edited 7 years ago by DrewAPicture (previous) (diff)

#6 @tschutter
7 years ago

Thank you for the quick feedback! I processed all your feedback in doc-wp-user-query-args.29846.1.diff

Last edited 7 years ago by tschutter (previous) (diff)

@DrewAPicture
7 years ago

wrapping

#7 @DrewAPicture
7 years ago

  • Keywords has-patch added; needs-patch removed

doc-wp-user-query-args.29846.1.diff looks pretty good. I'll review it and get back to you shortly.

We also need to wrap the lines once they've reached the maximum length of about 80-120 characters, and that's just for general readability -- I've fixed the wrapping in 29846.diff to illustrate.

#8 @tschutter
7 years ago

Right, I misinterpreted the length, I thought the "description of the value" had to be about 80-120. Got it.

#9 @DrewAPicture
7 years ago

OK, here's some feedback on 29846.diff:

  • $meta_compare'meta_value' in the description should be $meta_value
  • $offset – Offset can be used even without pagination, though it relies on $number being set, so that should be mentioned. Perhaps "Can be used in conjunction with pagination."
  • $number – Same as $offset, is usable with or without pagination. Also, worth mentioning that -1 is not supported.

Everything else looks pretty good. Once you make these changes, it should be ready to go in!

#10 @tschutter
7 years ago

Added doc-wp-user-query-args.29846.2.diff with your proposed changes.

#12 @DrewAPicture
7 years ago

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

In 29843:

Add inline documentation for WP_User_Query default arguments in the form of a hash notation.

Adds documentation pointers from the class-level doc for WP_User_Query, as well as the get_users() doc.

Props tschutter.
Fixes #29846.

Note: See TracTickets for help on using tickets.