Docs: Various improvements to inline documentation.

See #62281

git-svn-id: https://develop.svn.wordpress.org/trunk@59896 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-admin/includes/misc.php

@@ -625,7 +625,7 @@ function show_message( $message ) {
  * @since 2.8.0
  *
  * @param string $content
- * @return array
+ * @return string[] Array of function names.
  */
 function wp_doc_link_parse( $content ) {
 	if ( ! is_string( $content ) || empty( $content ) ) {

src/wp-admin/includes/post.php

@@ -493,7 +493,13 @@ function edit_post( $post_data = null ) {
  *
  * @param array|null $post_data Optional. The array of post data to process.
  *                              Defaults to the `$_POST` superglobal.
- * @return array
+ * @return array {
+ *     An array of updated, skipped, and locked post IDs.
+ *
+ *     @type int[] $updated An array of updated post IDs.
+ *     @type int[] $skipped An array of skipped post IDs.
+ *     @type int[] $locked  An array of locked post IDs.
+ * }
  */
 function bulk_edit_posts( $post_data = null ) {
 	global $wpdb;
@@ -1211,7 +1217,7 @@ function get_available_post_statuses( $type = 'post' ) {
  *
  * @param array|false $q Optional. Array of query variables to use to build the query.
  *                       Defaults to the `$_GET` superglobal.
- * @return array
+ * @return string[] An array of all the statuses for the queried post type.
  */
 function wp_edit_posts_query( $q = false ) {
 	if ( false === $q ) {
@@ -1383,7 +1389,12 @@ function wp_edit_attachments_query_vars( $q = false ) {
  *
  * @param array|false $q Optional. Array of query variables to use to build the query.
  *                       Defaults to the `$_GET` superglobal.
- * @return array
+ * @return array {
+ *     Array containing the post mime types and available post mime types.
+ *
+ *     @type array[]  $post_mime_types       Post mime types.
+ *     @type string[] $avail_post_mime_types Available post mime types.
+ * }
  */
 function wp_edit_attachments_query( $q = false ) {
 	wp( wp_edit_attachments_query_vars( $q ) );

src/wp-admin/includes/user.php

@@ -313,7 +313,7 @@ function get_users_drafts( $user_id ) {
 	$query = $wpdb->prepare( "SELECT ID, post_title FROM $wpdb->posts WHERE post_type = 'post' AND post_status = 'draft' AND post_author = %d ORDER BY post_modified DESC", $user_id );
 
 	/**
-	 * Filters the user's drafts query string.
+	 * Filters the SQL query string for the user's drafts query.
 	 *
 	 * @since 2.0.0
 	 *

src/wp-includes/script-loader.php

@@ -2095,7 +2095,7 @@ function wp_style_loader_src( $src, $handle ) {
  *
  * @global bool $concatenate_scripts
  *
- * @return array
+ * @return string[] Handles of the scripts that were printed.
  */
 function print_head_scripts() {
 	global $concatenate_scripts;
@@ -2134,7 +2134,7 @@ function print_head_scripts() {
  * @global WP_Scripts $wp_scripts
  * @global bool       $concatenate_scripts
  *
- * @return array
+ * @return string[] Handles of the scripts that were printed.
  */
 function print_footer_scripts() {
 	global $wp_scripts, $concatenate_scripts;
@@ -2215,7 +2215,7 @@ function _print_scripts() {
  *
  * @global WP_Scripts $wp_scripts
  *
- * @return array
+ * @return string[] Handles of the scripts that were printed.
  */
 function wp_print_head_scripts() {
 	global $wp_scripts;
@@ -2280,7 +2280,7 @@ function wp_enqueue_scripts() {
  *
  * @global bool $concatenate_scripts
  *
- * @return array
+ * @return string[] Handles of the styles that were printed.
  */
 function print_admin_styles() {
 	global $concatenate_scripts;

src/wp-includes/update.php

@@ -891,7 +891,12 @@ function wp_get_translation_updates() {
  *
  * @since 3.3.0
  *
- * @return array
+ * @return array {
+ *     Fetched update data.
+ *
+ *     @type int[]   $counts       An array of counts for available plugin, theme, and WordPress updates.
+ *     @type string  $update_title Titles of available updates.
+ * }
  */
 function wp_get_update_data() {
 	$counts = array(

tests/phpunit/includes/abstract-testcase.php

@@ -1462,7 +1462,7 @@ abstract class WP_UnitTestCase_Base extends PHPUnit_Adapter_TestCase {
 	 * @since 4.0.0
 	 *
 	 * @param string $dir Path to the directory to scan.
-	 * @return array List of file paths.
+	 * @return string[] List of file paths.
 	 */
 	public function files_in_dir( $dir ) {
 		$files = array();
@@ -1483,7 +1483,7 @@ abstract class WP_UnitTestCase_Base extends PHPUnit_Adapter_TestCase {
 	 *
 	 * @since 4.0.0
 	 *
-	 * @return array List of file paths.
+	 * @return string[] List of file paths.
 	 */
 	public function scan_user_uploads() {
 		static $files = array();