Docs: Improve documentation for install_plugin_install_status().

Props clarionwpdeveloper, sudar.
Fixes #36912.
Built from https://develop.svn.wordpress.org/trunk@38805


git-svn-id: http://core.svn.wordpress.org/trunk@38748 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-admin/includes/plugin-install.php

@@ -348,9 +348,16 @@ function display_plugins_table() {
  *
  * @since 3.0.0
  *
- * @param array|object $api
- * @param bool        $loop
- * @return type
+ * @param  array|object $api  Data about the plugin retrieved from the API.
+ * @param  bool         $loop Optional. Disable further loops. Default false.
+ * @return array {
+ *     Plugin installation status data.
+ *
+ *     @type string $status  Status of a plugin. Could be one of 'install', 'update_available', 'latest_installed' or 'newer_installed'.
+ *     @type string $url     Plugin installation URL.
+ *     @type string $version The most recent version of the plugin.
+ *     @type string $file    Plugin filename relative to the plugins directory.
+ * }
  */
 function install_plugin_install_status($api, $loop = false) {
 	// This function is called recursively, $loop prevents further loops.