Make WordPress Core

Opened 5 years ago

Closed 3 years ago

#44443 closed defect (bug) (fixed)

Confusing Documentation in WP_Term_Query::__construct()

Reported by: jeremyescott's profile jeremyescott Owned by: drewapicture's profile DrewAPicture
Milestone: 5.6 Priority: normal
Severity: minor Version:
Component: Query Keywords: has-patch dev-feedback
Focuses: docs Cc:


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 5 years ago.
Modify document block to more accurately describe the 'count' argument

Download all attachments as: .zip

Change History (10)

#1 @jeremyescott
5 years ago

  • Severity changed from normal to minor

#2 @jeremyescott
5 years 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
5 years 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

5 years ago

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

#4 @jeremyescott
5 years ago

  • Keywords has-patch added

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

#5 @jeremyescott
5 years 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.

5 years ago

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

5 years ago

#8 @DrewAPicture
3 years ago

  • Milestone changed from Awaiting Review to 5.6
  • Owner set to DrewAPicture
  • Status changed from new to reviewing

#9 @DrewAPicture
3 years ago

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

In 49189:

Docs: Clarify documentation for what the 'count' orderby argument represents in WP_Term_Query.

Props jeremyescott.
Fixes #44443.

Note: See TracTickets for help on using tickets.