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

See #47364, #50768

Built from https://develop.svn.wordpress.org/trunk@49020


git-svn-id: http://core.svn.wordpress.org/trunk@48782 1a063a9b-81f0-0310-95a4-ce76da25c4cd

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
 		 *

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.
  */

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 ) {

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', "<a href='" . esc_url( $url ) . "'>$link_text</a>", $id, $size, $permalink, $icon, $text, $attr );
 }

wp-includes/version.php

@@ -13,7 +13,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.6-alpha-49019';
+$wp_version = '5.6-alpha-49020';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.