From 3e56dfc905bac17f6a4399ae2e834420463903bd Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Sun, 2 Mar 2025 00:41:48 +0000 Subject: [PATCH] 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 | 2 +- src/wp-admin/includes/post.php | 17 ++++++++++++++--- src/wp-admin/includes/user.php | 2 +- src/wp-includes/script-loader.php | 8 ++++---- src/wp-includes/update.php | 7 ++++++- tests/phpunit/includes/abstract-testcase.php | 4 ++-- 6 files changed, 28 insertions(+), 12 deletions(-) diff --git a/src/wp-admin/includes/misc.php b/src/wp-admin/includes/misc.php index 0659938182..61b69aafee 100644 --- a/src/wp-admin/includes/misc.php +++ b/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 ) ) { diff --git a/src/wp-admin/includes/post.php b/src/wp-admin/includes/post.php index e5e1e5d147..5592753ae6 100644 --- a/src/wp-admin/includes/post.php +++ b/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 ) ); diff --git a/src/wp-admin/includes/user.php b/src/wp-admin/includes/user.php index abed2d2015..2f348ba841 100644 --- a/src/wp-admin/includes/user.php +++ b/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 * diff --git a/src/wp-includes/script-loader.php b/src/wp-includes/script-loader.php index fd5099a18e..63518ef5f9 100644 --- a/src/wp-includes/script-loader.php +++ b/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; diff --git a/src/wp-includes/update.php b/src/wp-includes/update.php index c51718a634..bf5d9b24d8 100644 --- a/src/wp-includes/update.php +++ b/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( diff --git a/tests/phpunit/includes/abstract-testcase.php b/tests/phpunit/includes/abstract-testcase.php index b6c82cc066..f665bdafb1 100644 --- a/tests/phpunit/includes/abstract-testcase.php +++ b/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();