Improve documentation for install_plugin_install_status()

[swissspidy]

The helper function install_plugin_install_status() is currently lacking some proper documentation. Besides not stating what exactly can be passed to the function, the return type is currently declared as type instead of array.

[DrewAPicture]

Assigning to mark the good-first-bug as "claimed".

See plugin-install.php.patch​

[swissspidy]

The patch needs a little bit more work. It needs to explain what exactly $loop does and what kind of array is being returned.

[clarionwpdeveloper]

I added more details of the $loop and return array.

[DrewAPicture]

@clarionwpdeveloper thanks for the updated patch. We should use the hash-notation style to document the return array. See the return notation for get_plugin_data() for a hint on how to do that.

[clarionwpdeveloper]

I added hash-notation style to document the return array.

[jorbin]

@DrewAPicture Can you take a look at the new patch?

[sudar]

Tweaked the docs a bit and fixed whitespace.

[swissspidy]

@sudar Thanks, this is getting along nicely.

Note that optional parameters should be documented according to the standards, see ​https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#docblock-formatting. Also, Date about the plugin should probably be something like Data about the plugin retrieved from the API.

[sudar]

@swissspidy Thanks for reviewing it.

I am attaching the modified patch after implementing the changes you suggested.

[swissspidy]

In 38805:

Docs: Improve documentation for install_plugin_install_status().

Props clarionwpdeveloper, sudar.
Fixes #36912.