From 7de213856be13f0e07bdfca788d3f8ff6c3a873e Mon Sep 17 00:00:00 2001
From: Gary Pendergast <pento@git.wordpress.org>
Date: Mon, 14 Jan 2019 06:53:44 +0000
Subject: [PATCH] Docs: Improve docblocks for
 `_get_plugin_data_markup_translate()` and `_sort_uname_callback()`.

Props Jaydeep Rami.
Fixes #42228.



git-svn-id: https://develop.svn.wordpress.org/trunk@44581 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-admin/includes/plugin.php | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/src/wp-admin/includes/plugin.php b/src/wp-admin/includes/plugin.php
index 6c7b62db93..85d3d5bb07 100644
--- a/src/wp-admin/includes/plugin.php
+++ b/src/wp-admin/includes/plugin.php
@@ -114,8 +114,29 @@ function get_plugin_data( $plugin_file, $markup = true, $translate = true ) {
  * Sanitizes plugin data, optionally adds markup, optionally translates.
  *
  * @since 2.7.0
- * @access private
+ *
  * @see get_plugin_data()
+ *
+ * @access private
+ *
+ * @param string $plugin_file Path to the main plugin file.
+ * @param array  $plugin_data An array of plugin data. See `get_plugin_data()`.
+ * @param bool   $markup      Optional. If the returned data should have HTML markup applied.
+ *                            Default true.
+ * @param bool   $translate   Optional. If the returned data should be translated. Default true.
+ * @return array {
+ *     Plugin data. Values will be empty if not supplied by the plugin.
+ *
+ *     @type string $Name        Name of the plugin. Should be unique.
+ *     @type string $Title       Title of the plugin and link to the plugin's site (if set).
+ *     @type string $Description Plugin description.
+ *     @type string $Author      Author's name.
+ *     @type string $AuthorURI   Author's website address (if set).
+ *     @type string $Version     Plugin version.
+ *     @type string $TextDomain  Plugin textdomain.
+ *     @type string $DomainPath  Plugins relative directory path to .mo files.
+ *     @type bool   $Network     Whether the plugin can only be activated network-wide.
+ * }
  */
 function _get_plugin_data_markup_translate( $plugin_file, $plugin_data, $markup = true, $translate = true ) {
 
@@ -376,7 +397,12 @@ function get_mu_plugins() {
  * Callback to sort array by a 'Name' key.
  *
  * @since 3.1.0
+ *
  * @access private
+ *
+ * @param array $a array with 'Name' key.
+ * @param array $b array with 'Name' key.
+ * @return int Return 0 or 1 based on two string comparison.
  */
 function _sort_uname_callback( $a, $b ) {
 	return strnatcasecmp( $a['Name'], $b['Name'] );