WordPress.org

Make WordPress Core

Opened 4 weeks ago

Last modified 2 weeks ago

#44443 new defect (bug)

Confusing Documentation in WP_Term_Query::__construct()

Reported by: jeremyescott Owned by:
Milestone: Awaiting Review Priority: normal
Severity: minor Version:
Component: Query Keywords: has-patch dev-feedback
Focuses: docs Cc:

Description

So I'm working on a pesky issue around a get_terms() call that, of course, uses WP_Term_Query::construct() and, while I fixed the issue (it was my fault) I spent some time in docs and in fact I got quite confused by an aspect of documentation, which I fully believe is an error.

from wp-includes/class-wp-term-query.php: 99

/* [...]
 *     @type string       $orderby                Field(s) to order terms by. Accepts term fields ('name',
 *                                                'slug', 'term_group', 'term_id', 'id', 'description', 'parent'),
 *                                                'count' for term taxonomy count, 'include' to match the
 *                                                'order' of the $include param, 'slug__in' to match the
 *                                                'order' of the $slug param, 'meta_value', 'meta_value_num',
 *                                                the value of `$meta_key`, the array keys of `$meta_query`, or
 *                                                'none' to omit the ORDER BY clause. Defaults to 'name'.
 * [...]
 */

My problem is with this bit:

'count' for term taxonomy count,

A term doesn't have taxonomy, right? A taxonomy has terms, but not terms taxonomy. I personally believe this should read (because it matches behavior):

'count' for number of posts in term count

Or something like that.

Is this correct? I don't think I'm crazy, but I'd love a second opinion. If I get some agreement, I'll either happily write a patch or let this one be a "good-first-patch" for a newbie!

Attachments (1)

44443.diff (1.5 KB) - added by jeremyescott 4 weeks ago.
Modify document block to more accurately describe the 'count' argument

Download all attachments as: .zip

Change History (8)

#1 @jeremyescott
4 weeks ago

  • Severity changed from normal to minor

#2 @jeremyescott
4 weeks ago

I'm so sorry! What a terrible title. I read and re-read the post content and didn't write a proper title.

#3 @subrataemfluence
4 weeks ago

Hi welcome to Trac and thanks for the ticket. Yes, taxonomy has terms, not the other way round!

So I think it could be reworded like this:

...
* 'count' for taxonomy term count
...

@jeremyescott
4 weeks ago

Modify document block to more accurately describe the 'count' argument

#4 @jeremyescott
4 weeks ago

  • Keywords has-patch added

Documentation is very subjective. Here is a stab at it.

#5 @jeremyescott
3 weeks ago

  • Keywords dev-feedback added
  • Summary changed from WP_Term_Query::__construct() to Confusing Documentation in WP_Term_Query::__construct()

This ticket was mentioned in Slack in #core by jeremyescott. View the logs.


2 weeks ago

This ticket was mentioned in Slack in #core-docs by jeremyescott. View the logs.


2 weeks ago

Note: See TracTickets for help on using tickets.