From 47abf85ab8f343c7790a611d91592471c886359d Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Fri, 9 Feb 2018 17:25:22 +0000 Subject: [PATCH] Docs: First pass at switching some array parameter documentation to typed notation. Props janak007 See #41756 git-svn-id: https://develop.svn.wordpress.org/trunk@42679 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-admin/includes/file.php | 44 +++++++++++++++--------------- src/wp-admin/includes/nav-menu.php | 19 +++++++------ 2 files changed, 32 insertions(+), 31 deletions(-) diff --git a/src/wp-admin/includes/file.php b/src/wp-admin/includes/file.php index 254c591982..415befc460 100644 --- a/src/wp-admin/includes/file.php +++ b/src/wp-admin/includes/file.php @@ -122,10 +122,10 @@ function get_home_path() { * @since 2.6.0 * @since 4.9.0 Added the `$exclusions` parameter. * - * @param string $folder Optional. Full path to folder. Default empty. - * @param int $levels Optional. Levels of folders to follow, Default 100 (PHP Loop limit). - * @param array $exclusions Optional. List of folders and files to skip. - * @return bool|array False on failure, Else array of files + * @param string $folder Optional. Full path to folder. Default empty. + * @param int $levels Optional. Levels of folders to follow, Default 100 (PHP Loop limit). + * @param string[] $exclusions Optional. List of folders and files to skip. + * @return bool|string[] False on failure, else array of files. */ function list_files( $folder = '', $levels = 100, $exclusions = array() ) { if ( empty( $folder ) ) { @@ -175,8 +175,8 @@ function list_files( $folder = '', $levels = 100, $exclusions = array() ) { * * @since 4.9.0 * - * @param string $plugin Plugin. - * @return array File extensions. + * @param string $plugin Path to the main plugin file from plugins directory. + * @return string[] Array of editable file extensions. */ function wp_get_plugin_file_editable_extensions( $plugin ) { @@ -221,8 +221,8 @@ function wp_get_plugin_file_editable_extensions( $plugin ) { * @since 2.8.0 * @since 4.9.0 Added the `$plugin` parameter. * - * @param string $plugin Plugin file. - * @param array $editable_extensions An array of editable plugin file extensions. + * @param string[] $editable_extensions An array of editable plugin file extensions. + * @param string $plugin Path to the main plugin file from plugins directory. */ $editable_extensions = (array) apply_filters( 'editable_extensions', $editable_extensions, $plugin ); @@ -232,8 +232,8 @@ function wp_get_plugin_file_editable_extensions( $plugin ) { /** * Get list of file extensions that are editable for a given theme. * - * @param WP_Theme $theme Theme. - * @return array File extensions. + * @param WP_Theme $theme Theme object. + * @return string[] Array of editable file extensions. */ function wp_get_theme_file_editable_extensions( $theme ) { @@ -277,7 +277,7 @@ function wp_get_theme_file_editable_extensions( $theme ) { * * @since 4.4.0 * - * @param array $default_types List of file types. Default types include 'php' and 'css'. + * @param string[] $default_types List of allowed file types. * @param WP_Theme $theme The current Theme object. */ $file_types = apply_filters( 'wp_theme_editor_filetypes', $default_types, $theme ); @@ -337,7 +337,7 @@ function wp_print_file_editor_templates() { * * @since 4.9.0 * - * @param array $args { + * @param string[] $args { * Args. Note that all of the arg values are already unslashed. They are, however, * coming straight from `$_POST` and are not validated or sanitized in any way. * @@ -662,9 +662,9 @@ function wp_tempnam( $filename = '', $dir = '' ) { * * @since 1.5.0 * - * @param string $file File the user is attempting to edit. - * @param array $allowed_files Optional. Array of allowed files to edit, $file must match an entry exactly. - * @return string|null + * @param string $file File the user is attempting to edit. + * @param string[] $allowed_files Optional. Array of allowed files to edit. `$file` must match an entry exactly. + * @return string|void Returns the file name on success, dies on failure. */ function validate_file_to_edit( $file, $allowed_files = array() ) { $code = validate_file( $file, $allowed_files ); @@ -694,12 +694,12 @@ function validate_file_to_edit( $file, $allowed_files = array() ) { * * @see wp_handle_upload_error * - * @param array $file Reference to a single element of $_FILES. Call the function once for each uploaded file. - * @param array|false $overrides An associative array of names => values to override default variables. Default false. - * @param string $time Time formatted in 'yyyy/mm'. - * @param string $action Expected value for $_POST['action']. - * @return array On success, returns an associative array of file attributes. On failure, returns - * $overrides['upload_error_handler'](&$file, $message ) or array( 'error'=>$message ). + * @param string[] $file Reference to a single element of `$_FILES`. Call the function once for each uploaded file. + * @param string[]|false $overrides An associative array of names => values to override default variables. Default false. + * @param string $time Time formatted in 'yyyy/mm'. + * @param string $action Expected value for `$_POST['action']`. + * @return string[] On success, returns an associative array of file attributes. On failure, returns + * `$overrides['upload_error_handler'](&$file, $message )` or `array( 'error'=>$message )`. */ function _wp_handle_upload( &$file, $overrides, $time, $action ) { // The default error handler. @@ -717,7 +717,7 @@ function _wp_handle_upload( &$file, $overrides, $time, $action ) { * @since 2.9.0 as 'wp_handle_upload_prefilter'. * @since 4.0.0 Converted to a dynamic hook with `$action`. * - * @param array $file An array of data for a single file. + * @param string[] $file An array of data for a single file. */ $file = apply_filters( "{$action}_prefilter", $file ); diff --git a/src/wp-admin/includes/nav-menu.php b/src/wp-admin/includes/nav-menu.php index 74209af075..5b8bfd7e00 100644 --- a/src/wp-admin/includes/nav-menu.php +++ b/src/wp-admin/includes/nav-menu.php @@ -461,10 +461,10 @@ function wp_nav_menu_item_post_type_meta_box( $object, $box ) { * @since 4.3.0 * @since 4.9.0 Added the `$recent_args` parameter. * - * @param array $most_recent An array of post objects being listed. - * @param array $args An array of WP_Query arguments for the meta box. - * @param array $box Arguments passed to wp_nav_menu_item_post_type_meta_box(). - * @param array $recent_args An array of WP_Query arguments for 'Most Recent' tab. + * @param WP_Post[] $most_recent An array of post objects being listed. + * @param array $args An array of `WP_Query` arguments for the meta box. + * @param array $box Arguments passed to `wp_nav_menu_item_post_type_meta_box()`. + * @param array $recent_args An array of `WP_Query` arguments for 'Most Recent' tab. */ $most_recent = apply_filters( "nav_menu_items_{$post_type_name}_recent", $most_recent, $args, $box, $recent_args ); @@ -589,8 +589,9 @@ function wp_nav_menu_item_post_type_meta_box( $object, $box ) { * * @see WP_Query::query() * - * @param array $posts The posts for the current post type. - * @param array $args An array of WP_Query arguments. + * @param object[] $posts The posts for the current post type. Mostly `WP_Post` objects, but + * can also contain "fake" post objects to represent other menu items. + * @param array $args An array of `WP_Query` arguments. * @param WP_Post_Type $post_type The current post type object for this menu item meta box. */ $posts = apply_filters( "nav_menu_items_{$post_type_name}", $posts, $args, $post_type ); @@ -889,9 +890,9 @@ function wp_nav_menu_item_taxonomy_meta_box( $object, $box ) { * * @since 3.0.0 * - * @param int $menu_id The menu ID for which to save this item. $menu_id of 0 makes a draft, orphaned menu item. - * @param array $menu_data The unsanitized posted menu item data. - * @return array The database IDs of the items saved + * @param int $menu_id The menu ID for which to save this item. Value of 0 makes a draft, orphaned menu item. Default 0. + * @param array[] $menu_data The unsanitized POSTed menu item data. + * @return int[] The database IDs of the items saved */ function wp_save_nav_menu_items( $menu_id = 0, $menu_data = array() ) { $menu_id = (int) $menu_id;