Requests::request_multiple() should have the option documentation in phpDoc

[johnbillion]

From https://core.trac.wordpress.org/ticket/48349:

Currently, the $options argument field is documented in the description:

https://developer.wordpress.org/reference/classes/requests/request_multiple/

I believe it could be documented using phpDoc directly like

@param array $options {
    Description.

    @type ...
}

Patch at https://core.trac.wordpress.org/attachment/ticket/48349/48349.2.patch

[jrfnl]

@johnbillion The @param array annotation used within WordPress is specific to WordPress and not recognized anywhere else, not in PSR 5/19, not in tooling like phpDocumentor etc.

As this package is not WP specific, I'd rather not use WP specific annotations.

[johnbillion]

Correct but as far as I know (although I don't follow them closely) neither PSR-5 nor PSR-19 propose such a syntax. What alternatives are there?

[jrfnl]

Either documenting the value as was done already, as part of the description. This is a common pattern.

Alternatively, a pattern like seen here can be used, where the @return tag contains a code sample of what the returned array looks like: https://github.com/PHPCSStandards/PHPCSUtils/blob/c677ffcf8b566ed5bf92b74a94a29241e969feda/PHPCSUtils/Utils/PassedParameters.php#L174-L185