Expand argument arrays in the function reference

[tellyworth]

Many WP functions use some form of $args array parameter, which leads to docs like this:

https://developer.wordpress.org/reference/functions/wp_update_post/

It would be great to pull in and expand the details of the array arguments so it's not necessary to click through to another page.

[iandunn]

That's a great idea!

To implement it, we'd need a way for the parser to know which function to pull. We could try to parse it out of the existing text using a regex, but that'd lead to false positives when a function is mentioned for a different purpose (rare?). It'd also be ambiguous when multiple functions are mentioned (also rare?).

It'd probably be better to create some kind of structured way to communicate that, but we still want it to be obvious when humans are reading the code in their IDEs too. PHPDoc's @see tag doesn't allow for a specific variable, but we could have a convention where the var name immediately follows.

/**
 * @param array|object $postarr Optional. Post data. Default array.
 *                              Arrays are expected to be escaped, objects are not.
 *                              @see wp_insert_post() $postarr for accepted arguments
 */

...or maybe format it like:

/**
 * @param array|object $postarr {
 *           Optional. Post data. Default array.
 *           Arrays are expected to be escaped, objects are not.
 * 
 *           @see wp_insert_post() $postarr for accepted arguments.
 * }
 */

[tellyworth]

Yep 100%. For the sprint we could use a few specially coded regexes or just hard-code some references for specific functions. That would let us demonstrate the results and make a case for adding a special keyword.

[dd32]

I took a look through the existing data.

Some examples (Sorry, I didn't take note of what functions they were for..)

See {@see register_meta()} for a list of supported arguments
See WP_Site_Query::__construct() for information on accepted arguments.
See wp_oembed_get() for accepted arguments.
Optional. Widget control options. See wp_register_widget_control(). Default empty array.
See WP_Date_Query::validate_column() and the {@see 'date_query_valid_columns'} filter for the list

[johnbillion]

We can and should standardise on this in core. The phrase "information on accepted arguments" appears 29 times and "for accepted arguments" appears 22 times but with a mixture of the formats Dion listed above.

If we do standardise on it then for it to be machine-readable we'd need a way to reference the target parameter name too, eg function2( $foo, $args ) might reference function1( $params ) and we'd want a reliable way to map from $args to $params in this case. Suggestions welcome for a good format for this.