From b6204405198eae8ccf08683064e84d6e85869b41 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Sun, 20 Sep 2020 15:53:52 +0000 Subject: [PATCH] Docs: Inline documentation improvements for media related functions and hooks. See #47364, #50768 git-svn-id: https://develop.svn.wordpress.org/trunk@49020 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-admin/includes/image.php | 10 +++++----- src/wp-admin/includes/media.php | 2 +- src/wp-includes/media.php | 21 +++++++++++++-------- src/wp-includes/post-template.php | 6 +++--- 4 files changed, 22 insertions(+), 17 deletions(-) diff --git a/src/wp-admin/includes/image.php b/src/wp-admin/includes/image.php index d0e714f573..3271eff1e4 100644 --- a/src/wp-admin/includes/image.php +++ b/src/wp-admin/includes/image.php @@ -966,10 +966,10 @@ function load_image_to_edit( $attachment_id, $mime_type, $size = 'full' ) { } /** - * 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 * @access private @@ -989,7 +989,7 @@ function _load_image_to_edit_path( $attachment_id, $size = 'full' ) { $filepath = path_join( dirname( $filepath ), $data['file'] ); /** - * 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'. * @@ -1004,9 +1004,9 @@ function _load_image_to_edit_path( $attachment_id, $size = 'full' ) { } } elseif ( function_exists( 'fopen' ) && ini_get( 'allow_url_fopen' ) ) { /** - * Filters the image URL if not in the local filesystem. + * Filters the path to an attachment's URL when editing the image. * - * The filter is only evaluated if fopen is enabled on the server. + * 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 * diff --git a/src/wp-admin/includes/media.php b/src/wp-admin/includes/media.php index d206aa163c..08f1dff5be 100644 --- a/src/wp-admin/includes/media.php +++ b/src/wp-admin/includes/media.php @@ -181,7 +181,7 @@ function get_image_send_to_editor( $id, $caption, $title, $align, $url = '', $re * @param string $title Image title attribute (not used). * @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. */ diff --git a/src/wp-includes/media.php b/src/wp-includes/media.php index 9dfc8b0b69..6b72aecc84 100644 --- a/src/wp-includes/media.php +++ b/src/wp-includes/media.php @@ -749,13 +749,13 @@ function wp_image_matches_ratio( $source_width, $source_height, $target_width, $ * Default 'thumbnail'. * @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. + * 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. + * @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. * } */ function image_get_intermediate_size( $post_id, $size = 'thumbnail' ) { @@ -1153,9 +1153,14 @@ function _wp_get_attachment_relative_path( $file ) { * @since 4.4.0 * @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 ) { if ( 'full' === $size_name ) { diff --git a/src/wp-includes/post-template.php b/src/wp-includes/post-template.php index 6a181d52c8..c53630acfc 100644 --- a/src/wp-includes/post-template.php +++ b/src/wp-includes/post-template.php @@ -1645,9 +1645,9 @@ function wp_get_attachment_link( $id = 0, $size = 'thumbnail', $permalink = fals * @param string|array $size Size of the image. Image size or array of width and height values (in that order). * 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', "$link_text", $id, $size, $permalink, $icon, $text, $attr ); }