[wp-trac] [WordPress Trac] #64813: Docs: Fix `@param` type for `get_posts()` and other functions using `wp_parse_args()`

[WordPress Trac]

#64813: Docs: Fix `@param` type for `get_posts()` and other functions using
`wp_parse_args()`
---------------------------+-----------------------------
 Reporter:  rodrigosprimo  |      Owner:  (none)
     Type:  defect (bug)   |     Status:  new
 Priority:  normal         |  Milestone:  Awaiting Review
Component:  General        |    Version:
 Severity:  normal         |   Keywords:
  Focuses:  docs           |
---------------------------+-----------------------------
 While working on a [https://github.com/WordPress/WordPress-Coding-
 Standards/pull/2699 WPCS PR], I noticed that the
 [https://github.com/WordPress/wordpress-
 develop/blob/8a7d2ceaad7006adcd1f67adc7a3047b79fe800e/src/wp-
 includes/post.php#L2616 get_posts()] function documents its `$args`
 parameter as `@param array $args`, but since `$args` is passed through
 `wp_parse_args()`, it also accepts a query string (e.g.,
 `'numberposts=5&post_type=page'`). The `@param` type should be
 `string|array` to reflect this.

 Other functions that also pass their `$args` through `wp_parse_args()`
 already correctly document `string|array`:

 * [https://github.com/WordPress/wordpress-
 develop/blob/8a7d2ceaad7006adcd1f67adc7a3047b79fe800e/src/wp-includes
 /category-template.php#L538 wp_list_categories()]
 * [https://github.com/WordPress/wordpress-
 develop/blob/8a7d2ceaad7006adcd1f67adc7a3047b79fe800e/src/wp-includes
 /category-template.php#L344 wp_dropdown_categories()]
 * [https://github.com/WordPress/wordpress-
 develop/blob/8a7d2ceaad7006adcd1f67adc7a3047b79fe800e/src/wp-includes
 /general-template.php#L2002 wp_get_archives()]
 * [https://github.com/WordPress/wordpress-
 develop/blob/8a7d2ceaad7006adcd1f67adc7a3047b79fe800e/src/wp-includes
 /post-template.php#L1303 wp_list_pages()]
 * [https://github.com/WordPress/wordpress-
 develop/blob/8a7d2ceaad7006adcd1f67adc7a3047b79fe800e/src/wp-
 includes/category.php#L26 get_categories()]
 * [https://github.com/WordPress/wordpress-
 develop/blob/8a7d2ceaad7006adcd1f67adc7a3047b79fe800e/src/wp-
 includes/taxonomy.php#L1316 get_terms()]

 == Other discussion points ==

 === More functions with `array` type ===

 Besides `get_posts()`, there is a significant number of other functions
 that document just `array` for parameters passed to `wp_parse_args()`.
 Here is a list of the ones I found on a quick search (there may be more):

 * [https://github.com/WordPress/wordpress-
 develop/blob/8a7d2ceaad7006adcd1f67adc7a3047b79fe800e/src/wp-
 includes/post.php#L4359 wp_get_post_categories()]
 * [https://github.com/WordPress/wordpress-
 develop/blob/8a7d2ceaad7006adcd1f67adc7a3047b79fe800e/src/wp-
 includes/post.php#L4406 wp_get_post_terms()]
 * [https://github.com/WordPress/wordpress-
 develop/blob/8a7d2ceaad7006adcd1f67adc7a3047b79fe800e/src/wp-
 includes/post.php#L4431 wp_get_recent_posts()]
 * [https://github.com/WordPress/wordpress-
 develop/blob/8a7d2ceaad7006adcd1f67adc7a3047b79fe800e/src/wp-
 includes/comment.php#L188 get_approved_comments()]
 * [https://github.com/WordPress/wordpress-
 develop/blob/8a7d2ceaad7006adcd1f67adc7a3047b79fe800e/src/wp-
 includes/comment.php#L1049 get_page_of_comment()]

 Should those be addressed as well?


 === Should `object` be included? ===

 `wp_parse_args()` itself is documented as `@param string|array|object
 $args`. None of the functions that pass `$args` through `wp_parse_args()`
 that I checked include `object` in their `@param` type. They all use
 `string|array` or just `array`. I wonder if `object` should also be
 documented for these functions for completeness, or if there is a reason
 why `object` is not included?

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/64813>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform