From eda6a9e111682475d399dbe27d5ac41ad25d82b6 Mon Sep 17 00:00:00 2001
From: John Blackbourn <johnbillion@git.wordpress.org>
Date: Tue, 5 Nov 2019 21:30:03 +0000
Subject: [PATCH] Docs: Docs on docs. Further improve documentation of known
 return types, plus other docs fixes.

See #48303

Built from https://develop.svn.wordpress.org/trunk@46662


git-svn-id: http://core.svn.wordpress.org/trunk@46462 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-admin/includes/bookmark.php                       |  6 +++---
 wp-admin/includes/class-wp-list-table.php            |  2 +-
 .../includes/class-wp-privacy-requests-table.php     |  6 +++---
 wp-admin/includes/class-wp-users-list-table.php      |  7 +++----
 wp-admin/includes/misc.php                           |  2 +-
 wp-admin/includes/nav-menu.php                       |  2 +-
 wp-admin/includes/plugin.php                         | 12 ++++++------
 wp-admin/includes/post.php                           |  8 ++++----
 wp-admin/includes/screen.php                         | 12 ++++++------
 wp-admin/includes/taxonomy.php                       |  2 +-
 wp-admin/includes/template.php                       | 12 ++++++------
 wp-admin/includes/theme.php                          |  4 ++--
 wp-admin/includes/translation-install.php            |  4 ++--
 wp-admin/includes/upgrade.php                        |  9 ++++++++-
 wp-includes/blocks.php                               |  4 ++--
 wp-includes/version.php                              |  2 +-
 16 files changed, 50 insertions(+), 44 deletions(-)

diff --git a/wp-admin/includes/bookmark.php b/wp-admin/includes/bookmark.php
index 6168a63529..66c1edb8b7 100644
--- a/wp-admin/includes/bookmark.php
+++ b/wp-admin/includes/bookmark.php
@@ -117,12 +117,12 @@ function wp_delete_link( $link_id ) {
 }
 
 /**
- * Retrieves the link categories associated with the link specified.
+ * Retrieves the link category IDs associated with the link specified.
  *
  * @since 2.1.0
  *
- * @param int $link_id Link ID to look up
- * @return array The requested link's categories
+ * @param int $link_id Link ID to look up.
+ * @return int[] The IDs of the requested link's categories.
  */
 function wp_get_link_cats( $link_id = 0 ) {
 	$cats = wp_get_object_terms( $link_id, 'link_category', array( 'fields' => 'ids' ) );
diff --git a/wp-admin/includes/class-wp-list-table.php b/wp-admin/includes/class-wp-list-table.php
index 3faaec691d..d4f18f7f2a 100644
--- a/wp-admin/includes/class-wp-list-table.php
+++ b/wp-admin/includes/class-wp-list-table.php
@@ -1217,7 +1217,7 @@ class WP_List_Table {
 	 *
 	 * @since 3.1.0
 	 *
-	 * @return array List of CSS classes for the table tag.
+	 * @return string[] Array of CSS classes for the table tag.
 	 */
 	protected function get_table_classes() {
 		return array( 'widefat', 'fixed', 'striped', $this->_args['plural'] );
diff --git a/wp-admin/includes/class-wp-privacy-requests-table.php b/wp-admin/includes/class-wp-privacy-requests-table.php
index efbd4a2a82..eb9643d42e 100644
--- a/wp-admin/includes/class-wp-privacy-requests-table.php
+++ b/wp-admin/includes/class-wp-privacy-requests-table.php
@@ -35,7 +35,7 @@ abstract class WP_Privacy_Requests_Table extends WP_List_Table {
 	 *
 	 * @since 4.9.6
 	 *
-	 * @return array Array of columns.
+	 * @return string[] Array of column titles keyed by their column name.
 	 */
 	public function get_columns() {
 		$columns = array(
@@ -137,7 +137,7 @@ abstract class WP_Privacy_Requests_Table extends WP_List_Table {
 	 *
 	 * @since 4.9.6
 	 *
-	 * @return array Associative array of views in the format of $view_name => $view_markup.
+	 * @return string[] An array of HTML links keyed by their view.
 	 */
 	protected function get_views() {
 		$current_status = isset( $_REQUEST['filter-status'] ) ? sanitize_text_field( $_REQUEST['filter-status'] ) : '';
@@ -200,7 +200,7 @@ abstract class WP_Privacy_Requests_Table extends WP_List_Table {
 	 *
 	 * @since 4.9.6
 	 *
-	 * @return array List of bulk actions.
+	 * @return string[] Array of bulk action labels keyed by their action.
 	 */
 	protected function get_bulk_actions() {
 		return array(
diff --git a/wp-admin/includes/class-wp-users-list-table.php b/wp-admin/includes/class-wp-users-list-table.php
index 8653df887a..b2c5c9b8e0 100644
--- a/wp-admin/includes/class-wp-users-list-table.php
+++ b/wp-admin/includes/class-wp-users-list-table.php
@@ -170,7 +170,7 @@ class WP_Users_List_Table extends WP_List_Table {
 	 *
 	 * @global string $role
 	 *
-	 * @return array An array of HTML links, one for each view.
+	 * @return string[] An array of HTML links keyed by their view.
 	 */
 	protected function get_views() {
 		global $role;
@@ -259,7 +259,7 @@ class WP_Users_List_Table extends WP_List_Table {
 	 *
 	 * @since  3.1.0
 	 *
-	 * @return array Array of bulk actions.
+	 * @return string[] Array of bulk action labels keyed by their action.
 	 */
 	protected function get_bulk_actions() {
 		$actions = array();
@@ -348,8 +348,7 @@ class WP_Users_List_Table extends WP_List_Table {
 	 *
 	 * @since  3.1.0
 	 *
-	 * @return array Array in which the key is the ID of the column,
-	 *               and the value is the description.
+	 * @return string[] Array of column titles keyed by their column name.
 	 */
 	public function get_columns() {
 		$c = array(
diff --git a/wp-admin/includes/misc.php b/wp-admin/includes/misc.php
index 1eb6aaa393..428b2980a5 100644
--- a/wp-admin/includes/misc.php
+++ b/wp-admin/includes/misc.php
@@ -62,7 +62,7 @@ function got_url_rewrite() {
  *
  * @param string $filename Filename to extract the strings from.
  * @param string $marker   The marker to extract the strings from.
- * @return array An array of strings from a file (.htaccess) from between BEGIN and END markers.
+ * @return string[] An array of strings from a file (.htaccess) from between BEGIN and END markers.
  */
 function extract_from_markers( $filename, $marker ) {
 	$result = array();
diff --git a/wp-admin/includes/nav-menu.php b/wp-admin/includes/nav-menu.php
index d10ce01594..acd68d112f 100644
--- a/wp-admin/includes/nav-menu.php
+++ b/wp-admin/includes/nav-menu.php
@@ -1085,7 +1085,7 @@ function wp_get_nav_menu_to_edit( $menu_id = 0 ) {
  *
  * @since 3.0.0
  *
- * @return array Columns.
+ * @return string[] Array of column titles keyed by their column name.
  */
 function wp_nav_menu_manage_columns() {
 	return array(
diff --git a/wp-admin/includes/plugin.php b/wp-admin/includes/plugin.php
index 32a37f106a..69da5dba9c 100644
--- a/wp-admin/includes/plugin.php
+++ b/wp-admin/includes/plugin.php
@@ -226,7 +226,7 @@ function _get_plugin_data_markup_translate( $plugin_file, $plugin_data, $markup
  * @since 2.8.0
  *
  * @param string $plugin Path to the plugin file relative to the plugins directory.
- * @return array List of files relative to the plugin root.
+ * @return string[] Array of file names relative to the plugin root.
  */
 function get_plugin_files( $plugin ) {
 	$plugin_file = WP_PLUGIN_DIR . '/' . $plugin;
@@ -273,7 +273,7 @@ function get_plugin_files( $plugin ) {
  * @since 1.5.0
  *
  * @param string $plugin_folder Optional. Relative path to single plugin folder.
- * @return array Key is the plugin file path and the value is an array of the plugin data.
+ * @return array[] Array of arrays of plugin data, keyed by plugin file name. See `get_plugin_data()`.
  */
 function get_plugins( $plugin_folder = '' ) {
 
@@ -354,7 +354,7 @@ function get_plugins( $plugin_folder = '' ) {
  * WordPress only includes mu-plugin files in the base mu-plugins directory (wp-content/mu-plugins).
  *
  * @since 3.0.0
- * @return array Key is the mu-plugin file path and the value is an array of the mu-plugin data.
+ * @return array[] Array of arrays of mu-plugin data, keyed by plugin file name. See `get_plugin_data()`.
  */
 function get_mu_plugins() {
 	$wp_plugins = array();
@@ -423,7 +423,7 @@ function _sort_uname_callback( $a, $b ) {
  * Check the wp-content directory and retrieve all drop-ins with any plugin data.
  *
  * @since 3.0.0
- * @return array Key is the file path and the value is an array of the plugin data.
+ * @return array[] Array of arrays of dropin plugin data, keyed by plugin file name. See `get_plugin_data()`.
  */
 function get_dropins() {
 	$dropins      = array();
@@ -471,7 +471,7 @@ function get_dropins() {
  * Includes Multisite drop-ins only when is_multisite()
  *
  * @since 3.0.0
- * @return array Key is file name. The value is an array, with the first value the
+ * @return array[] Key is file name. The value is an array, with the first value the
  *  purpose of the drop-in and the second value the name of the constant that must be
  *  true for the drop-in to be used, or true if no constant is required.
  */
@@ -1029,7 +1029,7 @@ function delete_plugins( $plugins, $deprecated = '' ) {
  * returns an array of deactivated ones.
  *
  * @since 2.5.0
- * @return array invalid plugins, plugin as key, error as value
+ * @return WP_Error[] Array of plugin errors keyed by plugin file name.
  */
 function validate_active_plugins() {
 	$plugins = get_option( 'active_plugins', array() );
diff --git a/wp-admin/includes/post.php b/wp-admin/includes/post.php
index 40dfd3971b..e99b9de6a4 100644
--- a/wp-admin/includes/post.php
+++ b/wp-admin/includes/post.php
@@ -1082,8 +1082,8 @@ function _fix_attachment_links( $post ) {
  *
  * @since 2.5.0
  *
- * @param string $type The post_type you want the statuses for
- * @return array As array of all the statuses for the supplied post type
+ * @param string $type The post_type you want the statuses for. Default 'post'.
+ * @return string[] An array of all the statuses for the supplied post type.
  */
 function get_available_post_statuses( $type = 'post' ) {
 	$stati = wp_count_posts( $type );
@@ -1492,7 +1492,7 @@ function get_sample_permalink_html( $id, $new_title = null, $new_slug = null ) {
  * @since 2.9.0
  *
  * @param int $thumbnail_id ID of the attachment used for thumbnail
- * @param mixed $post The post ID or object associated with the thumbnail, defaults to global $post.
+ * @param int|WP_Post $post Optional. The post ID or object associated with the thumbnail, defaults to global $post.
  * @return string html
  */
 function _wp_post_thumbnail_html( $thumbnail_id = null, $post = null ) {
@@ -2150,7 +2150,7 @@ function use_block_editor_for_post_type( $post_type ) {
  * @since 5.0.0
  *
  * @param WP_Post $post Post object.
- * @return array Array of block categories.
+ * @return array[] Array of block categories.
  */
 function get_block_categories( $post ) {
 	$default_categories = array(
diff --git a/wp-admin/includes/screen.php b/wp-admin/includes/screen.php
index 40a1a26fe3..6a2ccb742a 100644
--- a/wp-admin/includes/screen.php
+++ b/wp-admin/includes/screen.php
@@ -140,12 +140,12 @@ function meta_box_prefs( $screen ) {
 }
 
 /**
- * Get Hidden Meta Boxes
+ * Gets an array of IDs of hidden meta boxes.
  *
  * @since 2.7.0
  *
  * @param string|WP_Screen $screen Screen identifier
- * @return array Hidden Meta Boxes
+ * @return string[] IDs of hidden meta boxes.
  */
 function get_hidden_meta_boxes( $screen ) {
 	if ( is_string( $screen ) ) {
@@ -172,7 +172,7 @@ function get_hidden_meta_boxes( $screen ) {
 		 *
 		 * @since 3.1.0
 		 *
-		 * @param array     $hidden An array of meta boxes hidden by default.
+		 * @param string[]  $hidden An array of IDs of meta boxes hidden by default.
 		 * @param WP_Screen $screen WP_Screen object of the current screen.
 		 */
 		$hidden = apply_filters( 'default_hidden_meta_boxes', $hidden, $screen );
@@ -183,7 +183,7 @@ function get_hidden_meta_boxes( $screen ) {
 	 *
 	 * @since 3.3.0
 	 *
-	 * @param array     $hidden       An array of hidden meta boxes.
+	 * @param string[]  $hidden       An array of IDs of hidden meta boxes.
 	 * @param WP_Screen $screen       WP_Screen object of the current screen.
 	 * @param bool      $use_defaults Whether to show the default meta boxes.
 	 *                                Default true.
@@ -233,8 +233,8 @@ function get_current_screen() {
  *
  * @since 3.0.0
  *
- * @param mixed $hook_name Optional. The hook name (also known as the hook suffix) used to determine the screen,
- *                         or an existing screen object.
+ * @param string|WP_Screen $hook_name Optional. The hook name (also known as the hook suffix) used to determine the screen,
+ *                                    or an existing screen object.
  */
 function set_current_screen( $hook_name = '' ) {
 	WP_Screen::get( $hook_name )->set_current_screen();
diff --git a/wp-admin/includes/taxonomy.php b/wp-admin/includes/taxonomy.php
index 182231b683..1f8cab9956 100644
--- a/wp-admin/includes/taxonomy.php
+++ b/wp-admin/includes/taxonomy.php
@@ -73,7 +73,7 @@ function wp_create_category( $cat_name, $parent = 0 ) {
  *
  * @param string[] $categories Array of category names to create.
  * @param int      $post_id    Optional. The post ID. Default empty.
- * @return array List of categories to create for the given post.
+ * @return int[] Array of IDs of categories assigned to the given post.
  */
 function wp_create_categories( $categories, $post_id = '' ) {
 	$cat_ids = array();
diff --git a/wp-admin/includes/template.php b/wp-admin/includes/template.php
index 459793bcbd..4a21dd7b05 100644
--- a/wp-admin/includes/template.php
+++ b/wp-admin/includes/template.php
@@ -199,10 +199,10 @@ function wp_terms_checklist( $post_id = 0, $args = array() ) {
  * @since 2.5.0
  *
  * @param string $taxonomy Taxonomy to retrieve terms from.
- * @param int $default Not used.
- * @param int $number Number of terms to retrieve. Defaults to 10.
- * @param bool $echo Optionally output the list as well. Defaults to true.
- * @return array List of popular term IDs.
+ * @param int    $default  Not used.
+ * @param int    $number   Number of terms to retrieve. Defaults to 10.
+ * @param bool   $echo     Optionally output the list as well. Defaults to true.
+ * @return int[] Array of popular term IDs.
  */
 function wp_popular_terms_checklist( $taxonomy, $default = 0, $number = 10, $echo = true ) {
 	$post = get_post();
@@ -2097,12 +2097,12 @@ function _post_states( $post, $echo = true ) {
 }
 
 /**
- * Function to retrieve an array of post states from a post.
+ * Retrieves an array of post states from a post.
  *
  * @since 5.3.0
  *
  * @param WP_Post $post The post to retrieve states for.
- * @return array The array of translated post states.
+ * @return string[] Array of post state labels keyed by their state.
  */
 function get_post_states( $post ) {
 	$post_states = array();
diff --git a/wp-admin/includes/theme.php b/wp-admin/includes/theme.php
index 12035e1fc9..832fe89095 100644
--- a/wp-admin/includes/theme.php
+++ b/wp-admin/includes/theme.php
@@ -112,14 +112,14 @@ function delete_theme( $stylesheet, $redirect = '' ) {
 }
 
 /**
- * Get the Page Templates available in this theme
+ * Gets the page templates available in this theme.
  *
  * @since 1.5.0
  * @since 4.7.0 Added the `$post_type` parameter.
  *
  * @param WP_Post|null $post      Optional. The post being edited, provided for context.
  * @param string       $post_type Optional. Post type to get the templates for. Default 'page'.
- * @return array Key is the template name, value is the filename of the template
+ * @return string[] Array of template file names keyed by the template header name.
  */
 function get_page_templates( $post = null, $post_type = 'page' ) {
 	return array_flip( wp_get_theme()->get_page_templates( $post, $post_type ) );
diff --git a/wp-admin/includes/translation-install.php b/wp-admin/includes/translation-install.php
index f0de8fd6ee..093d21e53a 100644
--- a/wp-admin/includes/translation-install.php
+++ b/wp-admin/includes/translation-install.php
@@ -115,8 +115,8 @@ function translations_api( $type, $args = null ) {
  *
  * @see translations_api()
  *
- * @return array Array of translations, each an array of data. If the API response results
- *               in an error, an empty array will be returned.
+ * @return array[] Array of translations, each an array of data, keyed by the language. If the API response results
+ *                 in an error, an empty array will be returned.
  */
 function wp_get_available_translations() {
 	if ( ! wp_installing() ) {
diff --git a/wp-admin/includes/upgrade.php b/wp-admin/includes/upgrade.php
index 3b2d62da7c..86d7dedc78 100644
--- a/wp-admin/includes/upgrade.php
+++ b/wp-admin/includes/upgrade.php
@@ -35,7 +35,14 @@ if ( ! function_exists( 'wp_install' ) ) :
 	 * @param string $deprecated    Optional. Not used.
 	 * @param string $user_password Optional. User's chosen password. Default empty (random password).
 	 * @param string $language      Optional. Language chosen. Default empty.
-	 * @return array Array keys 'url', 'user_id', 'password', and 'password_message'.
+	 * @return array {
+	 *     Data for the newly installed site.
+	 *
+	 *     @type string $url              The URL of the site.
+	 *     @type int    $user_id          The ID of the site owner.
+	 *     @type string $password         The password of the site owner, if their user account didn't already exist.
+	 *     @type string $password_message The explanatory message regarding the password.
+	 * }
 	 */
 	function wp_install( $blog_title, $user_name, $user_email, $public, $deprecated = '', $user_password = '', $language = '' ) {
 		if ( ! empty( $deprecated ) ) {
diff --git a/wp-includes/blocks.php b/wp-includes/blocks.php
index e8647bf526..6a1928d20c 100644
--- a/wp-includes/blocks.php
+++ b/wp-includes/blocks.php
@@ -98,7 +98,7 @@ function has_block( $block_type, $post = null ) {
  *
  * @since 5.0.0
  *
- * @return array Array of dynamic block names.
+ * @return string[] Array of dynamic block names.
  */
 function get_dynamic_block_names() {
 	$dynamic_block_names = array();
@@ -281,7 +281,7 @@ function render_block( $block ) {
  * @since 5.0.0
  *
  * @param string $content Post content.
- * @return array Array of parsed block objects.
+ * @return array[] Array of parsed block objects.
  */
 function parse_blocks( $content ) {
 	/**
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 2432304967..a3c03d5c0c 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -13,7 +13,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.4-alpha-46661';
+$wp_version = '5.4-alpha-46662';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.