Make WordPress Core

Opened 22 months ago

Last modified 22 months ago

#56164 new enhancement

Create a way to reference function parameter documentation when complex parameters are passed to hooks

Reported by: desrosj's profile desrosj Owned by:
Milestone: Awaiting Review Priority: normal
Severity: normal Version:
Component: General Keywords: 2nd-opinion
Focuses: docs Cc:

Description

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 wp_insert_post_empty_content and 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.

Change History (2)

#1 @desrosj
22 months ago

I thought of this while creating a patch to add a filter for #34669.

The $args parameter there is documented in detail at the beginning of the function above. The idea was also inspired by comment:6:ticket:53946, which encourages a more consistent way to document the a return type when multiple types are possible and the type will match the one passed to the function.

Note: See TracTickets for help on using tickets.