Changeset 49020

Timestamp:

09/20/2020 03:53:52 PM (4 years ago)

Author:

johnbillion

Message:

Docs: Inline documentation improvements for media related functions and hooks.

See #47364, #50768

Location:

trunk/src

Files:

• wp-admin/includes/image.php (modified) (3 diffs)
• wp-admin/includes/media.php (modified) (1 diff)
• wp-includes/media.php (modified) (2 diffs)
• wp-includes/post-template.php (modified) (1 diff)

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

@@ -967 +967 @@
 
 /**
- * Retrieve the path or url of an attachment's attached file.
+ * Retrieve the path or URL of an attachment's attached file.
  *
  * If the attached file is not present on the local filesystem (usually due to replication plugins),
- * then the url of the file is returned if url fopen is supported.
+ * then the URL of the file is returned if `allow_url_fopen` is supported.
  *
  * @since 3.4.0
@@ -990 +990 @@
 
                 /**
-                 * Filters the path to the current image.
+                 * Filters the path to an attachment's file when editing the image.
                  *
                  * The filter is evaluated for all image sizes except 'full'.
@@ -1005 +1005 @@
     } elseif ( function_exists( 'fopen' ) && ini_get( 'allow_url_fopen' ) ) {
         /**
-         * Filters the image URL if not in the local filesystem.
-         *
-         * The filter is only evaluated if fopen is enabled on the server.
+         * Filters the path to an attachment's URL when editing the image.
+         *
+         * The filter is only evaluated if the file isn't stored locally and `allow_url_fopen` is enabled on the server.
          *
          * @since 3.1.0

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

@@ -182 +182 @@
  * @param string  $align   Image CSS alignment property.
  * @param string  $url     Image source URL (not used).
- * @param string  $size    Image size (`thumbnail`, `medium`, `large`, `full`, or added with `add_image_size()`) (not used).
+ * @param string  $size    Image size (not used).
  * @param string  $alt     Image `alt` attribute (not used).
  * @return string The image HTML markup with caption shortcode.

trunk/src/wp-includes/media.php

@@ -750 +750 @@
  * @return array|false {
  *     Array of file relative path, width, and height on success. Additionally includes absolute
- *     path and URL if registered size is passed to $size parameter. False on failure.
- *
- *     @type string $file   Image's path relative to uploads directory
- *     @type int    $width  Width of image
- *     @type int    $height Height of image
- *     @type string $path   Image's absolute filesystem path.
- *     @type string $url    Image's URL.
+ *     path and URL if registered size is passed to `$size` parameter. False on failure.
+ *
+ *     @type string $file   Path of image relative to uploads directory.
+ *     @type int    $width  Width of image in pixels.
+ *     @type int    $height Height of image in pixels.
+ *     @type string $path   Absolute filesystem path of image.
+ *     @type string $url    URL of image.
  * }
  */
@@ -1154 +1154 @@
  * @access private
  *
- * @param string $size_name  Image size. Accepts any valid image size name ('thumbnail', 'medium', etc.).
+ * @param string $size_name  Image size. Accepts any registered image size name.
  * @param array  $image_meta The image meta data.
- * @return array|bool The image meta data as returned by `wp_get_attachment_metadata()`.
+ * @return array|false {
+ *     Array of width and height or false if the size isn't present in the meta data.
+ *
+ *     @type int $0 Image width.
+ *     @type int $1 Image height.
+ * }
  */
 function _wp_get_image_size_from_meta( $size_name, $image_meta ) {

trunk/src/wp-includes/post-template.php

@@ -1646 +1646 @@
      *                                Default 'thumbnail'.
      * @param bool         $permalink Whether to add permalink to image. Default false.
-     * @param bool         $icon      Whether to include an icon. Default false.
-     * @param string|bool  $text      If string, will be link text. Default false.
-     * @param array|string $attr      Array or string of attributes. Default empty.
+     * @param bool         $icon      Whether to include an icon.
+     * @param string|bool  $text      If string, will be link text.
+     * @param array|string $attr      Array or string of attributes.
      */
     return apply_filters( 'wp_get_attachment_link', "<a href='" . esc_url( $url ) . "'>$link_text</a>", $id, $size, $permalink, $icon, $text, $attr );