Improve documentation for request_filesystem_credentials()

[swissspidy]

As per the @todo comment in request_filesystem_credentials(), the function's docblock could be improved a lot.

The params are not aligned correctly and, punctuation could be improved and proper descriptions for the optional params are needed.

See the ​PHP documentation standards for more details.

[slushman]

Add better documentation to DocBlock for request-filesystem-credentials().

[swissspidy]

@slushman Thanks for the patch!

Please note that I created this ticket specifically for the function request_filesystem_credentials(), not the WP_Upgrader_Skin::request_filesystem_credentials() method. (Of course that one needs some docs love too, but I'd rather do that in a separate ticket and for the whole class.)

Would you mind creating a new patch for request_filesystem_credentials() in wp-admin/includes/file.php? You can probably re-use some of the text used in the request_filesystem_credentials filter docs.

[danhgilmore]

Updated the docblock

[swissspidy]

I updated the patch again in 34858.2.diff​ to add default params and fix alignment of both the function and the filter DocBlocks.

[SergeyBiryukov]

In 35888:

Docs: Improve documentation for request_filesystem_credentials() and the corresponding filter.

Props swissspidy, danhgilmore, slushman.
Fixes #34858.