[wp-trac] [WordPress Trac] #56164: Create a way to reference function parameter documentation when complex parameters are passed to hooks

[WordPress Trac]

#56164: Create a way to reference function parameter documentation when complex
parameters are passed to hooks
-------------------------+-----------------------------
 Reporter:  desrosj      |      Owner:  (none)
     Type:  enhancement  |     Status:  new
 Priority:  normal       |  Milestone:  Awaiting Review
Component:  General      |    Version:
 Severity:  normal       |   Keywords:  2nd-opinion
  Focuses:  docs         |
-------------------------+-----------------------------
 When a parameter is passed to a filter or action hook that is also passed
 to the calling function itself, it's common for the `@param` tag on the
 hook to very briefly explain the parameter.

 For example, the `$postarr` parameter in `wp_insert_post()` is very
 complex. Though some modifications to the array are made prior, `$postarr`
 is ultimately passed to several filter hooks, such as
 [https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-
 includes/post.php#L4108-L4124 wp_insert_post_empty_content] and
 [https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-
 includes/post.php#L4348-L4376
 wp_insert_attachment_data/wp_insert_post_data]. The `@param` tags for
 these parameters within the filter hook documentation is very brief
 ("Array of post data." and "An array of slashed and sanitized attachment
 post data, but not processed." respectively).

 It would be great to have a way to remain brief within hook documentation
 in these scenarios while also referring someone to the more detailed,
 expanded documentation found for the function.

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