WordPress.org

Make WordPress Core

Opened 2 years ago

Closed 2 years ago

#40481 closed defect (bug) (fixed)

Inline docs for wp_get_post_tags() and wp_get_post_terms() don't reflect possible return values

Reported by: philipjohn Owned by: SergeyBiryukov
Milestone: 4.8 Priority: normal
Severity: normal Version: 4.7.3
Component: Taxonomy Keywords: has-patch
Focuses: docs Cc:

Description

It looks like the inline documentation for both wp_get_post_tags() and wp_get_post_terms() are missing possible return values, and some information on the nature of the possible return values.

wp_get_post_tags() has the following as the inline doc comment for the return value:

array List of post tags.

However, it might not return an array and while "list of post tags" is correct, that isn't entirely useful. The function will return an array of WP_Term objects, which is important information for a developer wanting to use the function.

And while wp_get_post_tags() sets the $taxonomy parameter when calling wp_get_post_terms() it's possible to remove that taxonomy, making it possible for wp_get_post_tags() to return a WP_Error object.

Similarly, wp_get_post_terms() uses "List of post terms or empty array" in it's inline docs on the return value. More useful is to know that it returns an array of WP_Term objects.

Attachments (1)

40481-1.patch (1.7 KB) - added by philipjohn 2 years ago.
Improves inline documentation by accounting for possible return values and expanding information on nature of array returned.

Download all attachments as: .zip

Change History (5)

@philipjohn
2 years ago

Improves inline documentation by accounting for possible return values and expanding information on nature of array returned.

#1 @ketuchetan
2 years ago

  • Keywords has-patch added

#2 @SergeyBiryukov
2 years ago

  • Milestone changed from Awaiting Review to 4.8

#3 @theMikeD
2 years ago

While you're in there, I suggest updating the $args description for wp_get_post_categories(), wp_get_post_tags(), and wp_get_post_terms() to be both accurate and identical since they all refer to the same thing. Perhaps something like

@param array|string $args       Optional. Array of term query parameters. Default empty. See WP_Term_Query::__construct() for supported arguments.

#4 @SergeyBiryukov
2 years ago

  • Owner set to SergeyBiryukov
  • Resolution set to fixed
  • Status changed from new to closed

In 40483:

Docs: Improve @param and @return entries for wp_get_post_categories(), wp_get_post_tags(), and wp_get_post_terms().

Props philipjohn, theMikeD.
Fixes #40481.

Note: See TracTickets for help on using tickets.