Changeset 51300 for trunk/src/wp-admin/includes/file.php

Timestamp:

07/01/2021 09:11:48 PM (4 years ago)

Author:

johnbillion

Message:

Docs: Descriptive improvements and corrections for various docblocks.

See #53399

File:

• trunk/src/wp-admin/includes/file.php (modified) (7 diffs)

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

@@ -734 +734 @@
  * @see wp_handle_upload_error
  *
- * @param string[]       $file      Reference to a single element of `$_FILES`.
- *                                  Call the function once for each uploaded file.
- * @param array|false    $overrides {
+ * @param array       $file      {
+ *     Reference to a single element from `$_FILES`. Call the function once for each uploaded file.
+ *
+ *     @type string $name     The original name of the file on the client machine.
+ *     @type string $type     The mime type of the file, if the browser provided this information.
+ *     @type string $tmp_name The temporary filename of the file in which the uploaded file was stored on the server.
+ *     @type int    $size     The size, in bytes, of the uploaded file.
+ *     @type int    $error    The error code associated with this file upload.
+ * }
+ * @param array|false $overrides {
  *     An array of override parameters for this file, or boolean false if none are provided.
  *
@@ -750 +757 @@
  *     @type string[] $mimes                    Array of allowed mime types keyed by their file extension regex.
  * }
- * @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 )`.
+ * @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 )`.
+ *
+ *     @type string $file Filename of the newly-uploaded file.
+ *     @type string $url  URL of the newly-uploaded file.
+ *     @type string $type Mime type of the newly-uploaded file.
+ * }
  */
 function _wp_handle_upload( &$file, $overrides, $time, $action ) {
@@ -777 +790 @@
      * @since 4.0.0 Converted to a dynamic hook with `$action`.
      *
-     * @param string[] $file An array of data for the file. Reference to a single element of `$_FILES`.
+     * @param array $file {
+     *     Reference to a single element from `$_FILES`.
+     *
+     *     @type string $name     The original name of the file on the client machine.
+     *     @type string $type     The mime type of the file, if the browser provided this information.
+     *     @type string $tmp_name The temporary filename of the file in which the uploaded file was stored on the server.
+     *     @type int    $size     The size, in bytes, of the uploaded file.
+     *     @type int    $error    The error code associated with this file upload.
+     * }
      */
     $file = apply_filters( "{$action}_prefilter", $file );
@@ -795 +816 @@
      * @param array|false $overrides An array of override parameters for this file. Boolean false if none are
      *                               provided. @see _wp_handle_upload().
-     * @param string[]    $file      An array of data for the file. Reference to a single element of `$_FILES`.
+     * @param array       $file      {
+     *     Reference to a single element from `$_FILES`.
+     *
+     *     @type string $name     The original name of the file on the client machine.
+     *     @type string $type     The mime type of the file, if the browser provided this information.
+     *     @type string $tmp_name The temporary filename of the file in which the uploaded file was stored on the server.
+     *     @type int    $size     The size, in bytes, of the uploaded file.
+     *     @type int    $error    The error code associated with this file upload.
+     * }
      */
     $overrides = apply_filters( "{$action}_overrides", $overrides, $file );
@@ -936 +965 @@
      *
      * @param mixed    $move_new_file If null (default) move the file after the upload.
-     * @param string[] $file          An array of data for a single file.
+     * @param array    $file          {
+     *     Reference to a single element from `$_FILES`.
+     *
+     *     @type string $name     The original name of the file on the client machine.
+     *     @type string $type     The mime type of the file, if the browser provided this information.
+     *     @type string $tmp_name The temporary filename of the file in which the uploaded file was stored on the server.
+     *     @type int    $size     The size, in bytes, of the uploaded file.
+     *     @type int    $error    The error code associated with this file upload.
+     * }
      * @param string   $new_file      Filename of the newly-uploaded file.
      * @param string   $type          Mime type of the newly-uploaded file.
@@ -1018 +1055 @@
  * @param array       $file      Reference to a single element of `$_FILES`.
  *                               Call the function once for each uploaded file.
+ *                               See _wp_handle_upload() for accepted values.
  * @param array|false $overrides Optional. An associative array of names => values
  *                               to override default variables. Default false.
+ *                               See _wp_handle_upload() for accepted values.
  * @param string      $time      Optional. Time formatted in 'yyyy/mm'. Default null.
- * @return array On success, returns an associative array of file attributes.
- *               On failure, returns `$overrides['upload_error_handler']( &$file, $message )`
- *               or `array( 'error' => $message )`.
+ * @return array See _wp_handle_upload() for return value.
  */
 function wp_handle_upload( &$file, $overrides = false, $time = null ) {
@@ -1049 +1086 @@
  * @param array       $file      Reference to a single element of `$_FILES`.
  *                               Call the function once for each uploaded file.
+ *                               See _wp_handle_upload() for accepted values.
  * @param array|false $overrides Optional. An associative array of names => values
  *                               to override default variables. Default false.
+ *                               See _wp_handle_upload() for accepted values.
  * @param string      $time      Optional. Time formatted in 'yyyy/mm'. Default null.
- * @return array On success, returns an associative array of file attributes.
- *               On failure, returns `$overrides['upload_error_handler']( &$file, $message )`
- *               or `array( 'error' => $message )`.
+ * @return array See _wp_handle_upload() for return value.
  */
 function wp_handle_sideload( &$file, $overrides = false, $time = null ) {