Changeset 42679

Timestamp:

02/09/2018 05:25:22 PM (7 years ago)

Author:

johnbillion

Message:

Docs: First pass at switching some array parameter documentation to typed notation.

Props janak007

See #41756

Location:

trunk/src/wp-admin/includes

Files:

• file.php (modified) (9 diffs)
• nav-menu.php (modified) (3 diffs)

trunk/src/wp-admin/includes/file.php

@@ -123 +123 @@
  * @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() ) {
@@ -176 +176 @@
  * @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 ) {
@@ -222 +222 @@
      * @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 );
@@ -233 +233 @@
  * 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 ) {
@@ -278 +278 @@
      * @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.
      */
@@ -338 +338 @@
  * @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.
@@ -663 +663 @@
  * @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() ) {
@@ -695 +695 @@
  * @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 ) {
@@ -718 +718 @@
      * @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 );

trunk/src/wp-admin/includes/nav-menu.php

@@ -462 +462 @@
                  * @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 );
@@ -590 +590 @@
                  * @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.
                  */
@@ -890 +891 @@
  * @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() ) {