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

[marekdedic]

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 ...
}

[marekdedic]

Also, I believe the return value could be narrowed from array to Requests_Response[]|Requests_Exception[].

[hogetan]

Fix option description

[hogetan]

Remove debug code

[dd32]

As the Requests class is an external project, ​https://developer.wordpress.org/reference/classes/requests/ probably shouldn't even exist, and documentation improvements should probably be discussed on ​it's Github project page.

[adamsilverstein]

I agree, it seems like the doc changes should be proposed and made upstream in the Requests project. Once we get changes merged there we can follow up to upgrade the core bundled version. Otherwise, if we make these changes only locally in WordPress core, they would get overwritten if/when we update the Requests version we bundle.

I searched through the ​open issues and didn't find anything about the documenting the option array there. It would be great to start by opening an issue describing the change. I believe there may be other opportunities to improve inline docs, especially arrays, elsewhere in the project.

Marking this ticket as future release for now, until we get the changes merged upstream.

[johnbillion]

​https://github.com/rmccue/Requests/issues/435