From 46286070a5e85dbd0c280d7a5dc09b44f4961456 Mon Sep 17 00:00:00 2001 From: Drew Jaynes Date: Tue, 24 Feb 2015 07:42:24 +0000 Subject: [PATCH] Clarify a wide variety of function, parameter, and return descriptions in DocBlocks throughout wp-includes/media.php. Props stevegrunwell, DrewAPicture. Fixes #28408. Built from https://develop.svn.wordpress.org/trunk@31530 git-svn-id: http://core.svn.wordpress.org/trunk@31511 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/media.php | 384 ++++++++++++++++++++++++---------------- wp-includes/version.php | 2 +- 2 files changed, 232 insertions(+), 154 deletions(-) diff --git a/wp-includes/media.php b/wp-includes/media.php index 4e95b56e46..f04ae19164 100644 --- a/wp-includes/media.php +++ b/wp-includes/media.php @@ -59,10 +59,12 @@ function image_constrain_size_for_editor( $width, $height, $size = 'medium', $co // if no width is set, default to the theme content width if available } elseif ( $size == 'large' ) { - // We're inserting a large size image into the editor. If it's a really - // big image we'll scale it down to fit reasonably within the editor - // itself, and within the theme's content width if it's known. The user - // can resize it in the editor if they wish. + /* + * We're inserting a large size image into the editor. If it's a really + * big image we'll scale it down to fit reasonably within the editor + * itself, and within the theme's content width if it's known. The user + * can resize it in the editor if they wish. + */ $max_width = intval(get_option('large_size_w')); $max_height = intval(get_option('large_size_h')); if ( intval($content_width) > 0 ) @@ -109,11 +111,11 @@ function image_constrain_size_for_editor( $width, $height, $size = 'medium', $co * * @since 2.5.0 * - * @param int|string $width Optional. Width attribute value. - * @param int|string $height Optional. Height attribute value. + * @param int|string $width Image width in pixels. + * @param int|string $height Image height in pixels. * @return string HTML attributes for width and, or height. */ -function image_hwstring($width, $height) { +function image_hwstring( $width, $height ) { $out = ''; if ($width) $out .= 'width="'.intval($width).'" '; @@ -140,11 +142,12 @@ function image_hwstring($width, $height) { * * @since 2.5.0 * - * @param int $id Attachment ID for image. - * @param array|string $size Optional, default is 'medium'. Size of image, either array or string. + * @param int $id Attachment ID for image. + * @param array|string $size Optional. Image size to scale to. Accepts a registered image size + * or flat array of height and width values. Default 'medium'. * @return bool|array False on failure, array on success. */ -function image_downsize($id, $size = 'medium') { +function image_downsize( $id, $size = 'medium' ) { if ( !wp_attachment_is_image($id) ) return false; @@ -284,7 +287,7 @@ function set_post_thumbnail_size( $width = 0, $height = 0, $crop = false ) { } /** - * An tag for an image attachment, scaling it down if requested. + * Gets an img tag for an image attachment, scaling it down if requested. * * The filter 'get_image_tag_class' allows for changing the class name for the * image without having to use regular expressions on the HTML content. The @@ -297,14 +300,15 @@ function set_post_thumbnail_size( $width = 0, $height = 0, $crop = false ) { * * @since 2.5.0 * - * @param int $id Attachment ID. - * @param string $alt Image Description for the alt attribute. - * @param string $title Image Description for the title attribute. - * @param string $align Part of the class name for aligning the image. - * @param string $size Optional. Default is 'medium'. + * @param int $id Attachment ID. + * @param string $alt Image Description for the alt attribute. + * @param string $title Image Description for the title attribute. + * @param string $align Part of the class name for aligning the image. + * @param string|array $size Optional. Registered image size to retrieve a tag for, or flat array + * of height and width values. Default 'medium'. * @return string HTML IMG element for given image attachment */ -function get_image_tag($id, $alt, $title, $align, $size='medium') { +function get_image_tag( $id, $alt, $title, $align, $size = 'medium' ) { list( $img_src, $width, $height ) = image_downsize($id, $size); $hwstring = image_hwstring($width, $height); @@ -345,20 +349,20 @@ function get_image_tag($id, $alt, $title, $align, $size='medium') { } /** - * Calculates the new dimensions for a downsampled image. + * Calculates the new dimensions for a down-sampled image. * * If either width or height are empty, no constraint is applied on * that dimension. * * @since 2.5.0 * - * @param int $current_width Current width of the image. + * @param int $current_width Current width of the image. * @param int $current_height Current height of the image. - * @param int $max_width Optional. Maximum wanted width. - * @param int $max_height Optional. Maximum wanted height. + * @param int $max_width Optional. Max width in pixels to constrain to. Default 0. + * @param int $max_height Optional. Max height in pixels to constrain to. Default 0. * @return array First item is the width, the second item is the height. */ -function wp_constrain_dimensions( $current_width, $current_height, $max_width=0, $max_height=0 ) { +function wp_constrain_dimensions( $current_width, $current_height, $max_width = 0, $max_height = 0 ) { if ( !$max_width && !$max_height ) return array( $current_width, $current_height ); @@ -405,11 +409,22 @@ function wp_constrain_dimensions( $current_width, $current_height, $max_width=0, $h = $max_height; // Round it up } + /** + * Filter dimensions to constrain down-sampled images to. + * + * @since 4.1.0 + * + * @param array $dimensions The image width and height. + * @param int $current_width The current width of the image. + * @param int $current_height The current height of the image. + * @param int $max_width The maximum width permitted. + * @param int $max_height The maximum height permitted. + */ return apply_filters( 'wp_constrain_dimensions', array( $w, $h ), $current_width, $current_height, $max_width, $max_height ); } /** - * Retrieve calculated resize dimensions for use in WP_Image_Editor. + * Retrieves calculated resize dimensions for use in WP_Image_Editor. * * Calculates dimensions and coordinates for a resized image that fits * within a specified width and height. @@ -523,7 +538,7 @@ function image_resize_dimensions($orig_w, $orig_h, $dest_w, $dest_h, $crop = fal } /** - * Resize an image to make a thumbnail or intermediate size. + * Resizes an image to make a thumbnail or intermediate size. * * The returned array has the file size, the image width, and image height. The * filter 'image_make_intermediate_size' can be used to hook in and change the @@ -531,10 +546,11 @@ function image_resize_dimensions($orig_w, $orig_h, $dest_w, $dest_h, $crop = fal * * @since 2.5.0 * - * @param string $file File path. - * @param int $width Image width. - * @param int $height Image height. - * @param bool $crop Optional, default is false. Whether to crop image to specified height and width or resize. + * @param string $file File path. + * @param int $width Image width. + * @param int $height Image height. + * @param bool $crop Optional. Whether to crop image to specified height and width or resize. + * Default false. * @return bool|array False, if no image was created. Metadata array on success. */ function image_make_intermediate_size( $file, $width, $height, $crop = false ) { @@ -555,7 +571,7 @@ function image_make_intermediate_size( $file, $width, $height, $crop = false ) { } /** - * Retrieve the image's intermediate size (resized) path, width, and height. + * Retrieves the image's intermediate size (resized) path, width, and height. * * The $size parameter can be an array with the width and height respectively. * If the size matches the 'sizes' metadata array for width and height, then it @@ -574,13 +590,13 @@ function image_make_intermediate_size( $file, $width, $height, $crop = false ) { * browser scale down the image. * * @since 2.5.0 - * @see add_image_size() * - * @param int $post_id Attachment ID for image. - * @param array|string $size Optional, default is 'thumbnail'. Size of image, either array or string. + * @param int $post_id Attachment ID. + * @param array|string $size Optional. Registered image size to retrieve or flat array of height + * and width dimensions. Default 'thumbnail'. * @return bool|array False on failure or array of file path, width, and height on success. */ -function image_get_intermediate_size($post_id, $size='thumbnail') { +function image_get_intermediate_size( $post_id, $size = 'thumbnail' ) { if ( !is_array( $imagedata = wp_get_attachment_metadata( $post_id ) ) ) return false; @@ -633,9 +649,13 @@ function image_get_intermediate_size($post_id, $size='thumbnail') { } /** - * Get the available image sizes + * Gets the available intermediate image sizes. + * * @since 3.0.0 - * @return array Returns a filtered array of image size strings + * + * @global array $_wp_additional_image_sizes + * + * @return array Returns a filtered array of image size strings. */ function get_intermediate_image_sizes() { global $_wp_additional_image_sizes; @@ -661,12 +681,13 @@ function get_intermediate_image_sizes() { * * @since 2.5.0 * - * @param int $attachment_id Image attachment ID. - * @param string $size Optional, default is 'thumbnail'. - * @param bool $icon Optional, default is false. Whether it is an icon. + * @param int $attachment_id Image attachment ID. + * @param string|array $size Optional. Registered image size to retrieve the source for or a flat + * array of height and width dimensions. Default 'thumbnail'. + * @param bool $icon Optional. Whether the image should be treated as an icon. Default false. * @return bool|array Returns an array (url, width, height), or false, if no image is available. */ -function wp_get_attachment_image_src($attachment_id, $size='thumbnail', $icon = false) { +function wp_get_attachment_image_src( $attachment_id, $size = 'thumbnail', $icon = false ) { // get a thumbnail or intermediate image if there is one if ( $image = image_downsize($attachment_id, $size) ) @@ -677,6 +698,7 @@ function wp_get_attachment_image_src($attachment_id, $size='thumbnail', $icon = if ( $icon && $src = wp_mime_type_icon($attachment_id) ) { /** This filter is documented in wp-includes/post.php */ $icon_dir = apply_filters( 'icon_dir', ABSPATH . WPINC . '/images/media' ); + $src_file = $icon_dir . '/' . wp_basename($src); @list($width, $height) = getimagesize($src_file); } @@ -688,19 +710,18 @@ function wp_get_attachment_image_src($attachment_id, $size='thumbnail', $icon = /** * Get an HTML img element representing an image attachment * - * While $size will accept an array, it is better to register a size with + * While `$size` will accept an array, it is better to register a size with * add_image_size() so that a cropped version is generated. It's much more * efficient than having to find the closest-sized image and then having the * browser scale down the image. * * @since 2.5.0 * - * @see add_image_size() - * * @param int $attachment_id Image attachment ID. - * @param string|array $size Optional. Default 'thumbnail'. - * @param bool $icon Optional. Whether it is an icon. Default false. - * @param string|array $attr Optional. Attributes for the image markup. Default empty string. + * @param string|array $size Optional. Registered image size or flat array of height and width + * dimensions. Default 'thumbnail'. + * @param bool $icon Optional. Whether the image should be treated as an icon. Default false. + * @param string|array $attr Optional. Attributes for the image markup. Default empty. * @return string HTML img element or empty string on failure. */ function wp_get_attachment_image($attachment_id, $size = 'thumbnail', $icon = false, $attr = '') { @@ -749,13 +770,16 @@ function wp_get_attachment_image($attachment_id, $size = 'thumbnail', $icon = fa } /** - * Adds a 'wp-post-image' class to post thumbnails - * Uses the begin_fetch_post_thumbnail_html and end_fetch_post_thumbnail_html action hooks to - * dynamically add/remove itself so as to only filter post thumbnails + * Adds a 'wp-post-image' class to post thumbnails. Internal use only. * + * Uses the 'begin_fetch_post_thumbnail_html' and 'end_fetch_post_thumbnail_html' action hooks to + * dynamically add/remove itself so as to only filter post thumbnails. + * + * @ignore * @since 2.9.0 - * @param array $attr Attributes including src, class, alt, title - * @return array + * + * @param array $attr Thumbnail attributes including src, class, alt, title. + * @return array Modified array of attributes including the new 'wp-post-image' class. */ function _wp_post_thumbnail_class_filter( $attr ) { $attr['class'] .= ' wp-post-image'; @@ -763,18 +787,26 @@ function _wp_post_thumbnail_class_filter( $attr ) { } /** - * Adds _wp_post_thumbnail_class_filter to the wp_get_attachment_image_attributes filter + * Adds '_wp_post_thumbnail_class_filter' callback to the 'wp_get_attachment_image_attributes' + * filter hook. Internal use only. * + * @ignore * @since 2.9.0 + * + * @param array $attr Thumbnail attributes including src, class, alt, title. */ function _wp_post_thumbnail_class_filter_add( $attr ) { add_filter( 'wp_get_attachment_image_attributes', '_wp_post_thumbnail_class_filter' ); } /** - * Removes _wp_post_thumbnail_class_filter from the wp_get_attachment_image_attributes filter + * Removes the '_wp_post_thumbnail_class_filter' callback from the 'wp_get_attachment_image_attributes' + * filter hook. Internal use only. * + * @ignore * @since 2.9.0 + * + * @param array $attr Thumbnail attributes including src, class, alt, title. */ function _wp_post_thumbnail_class_filter_remove( $attr ) { remove_filter( 'wp_get_attachment_image_attributes', '_wp_post_thumbnail_class_filter' ); @@ -784,7 +816,7 @@ add_shortcode('wp_caption', 'img_caption_shortcode'); add_shortcode('caption', 'img_caption_shortcode'); /** - * The Caption shortcode. + * Builds the Caption shortcode output. * * Allows a plugin to replace the content that would otherwise be returned. The * filter is 'img_caption_shortcode' and passes an empty string, the attr @@ -795,7 +827,7 @@ add_shortcode('caption', 'img_caption_shortcode'); * * @since 2.6.0 * - * @param array $attr { + * @param array $attr { * Attributes of the caption shortcode. * * @type string $id ID of the div element for the caption. @@ -805,7 +837,7 @@ add_shortcode('caption', 'img_caption_shortcode'); * @type string $caption The caption text. * @type string $class Additional class name(s) added to the caption container. * } - * @param string $content Optional. Shortcode content. + * @param string $content Shortcode content. * @return string HTML content to display the caption. */ function img_caption_shortcode( $attr, $content = null ) { @@ -887,7 +919,7 @@ function img_caption_shortcode( $attr, $content = null ) { add_shortcode('gallery', 'gallery_shortcode'); /** - * The Gallery shortcode. + * Builds the Gallery shortcode output. * * This implements the functionality of the Gallery Shortcode for displaying * WordPress images on a post. @@ -1105,7 +1137,7 @@ function gallery_shortcode( $attr ) { } /** - * Output the templates used by playlists. + * Outputs the templates used by playlists. * * @since 3.9.0 */ @@ -1143,7 +1175,7 @@ function wp_underscore_playlist_templates() { } /** - * Output and enqueue default scripts and styles for playlists. + * Outputs and enqueue default scripts and styles for playlists. * * @since 3.9.0 * @@ -1160,7 +1192,7 @@ function wp_playlist_scripts( $type ) { } /** - * The playlist shortcode. + * Builds the Playlist shortcode output. * * This implements the functionality of the playlist shortcode for displaying * a collection of WordPress audio or video files in a post. @@ -1406,12 +1438,12 @@ function wp_playlist_shortcode( $attr ) { add_shortcode( 'playlist', 'wp_playlist_shortcode' ); /** - * Provide a No-JS Flash fallback as a last resort for audio / video + * Provides a No-JS Flash fallback as a last resort for audio / video. * * @since 3.6.0 * - * @param string $url - * @return string Fallback HTML + * @param string $url The media element URL. + * @return string Fallback HTML. */ function wp_mediaelement_fallback( $url ) { /** @@ -1426,10 +1458,11 @@ function wp_mediaelement_fallback( $url ) { } /** - * Return a filtered list of WP-supported audio formats. + * Returns a filtered list of WP-supported audio formats. * * @since 3.6.0 - * @return array + * + * @return array Supported audio formats. */ function wp_get_audio_extensions() { /** @@ -1444,12 +1477,12 @@ function wp_get_audio_extensions() { } /** - * Return useful keys to use to lookup data from an attachment's stored metadata. + * Returns useful keys to use to lookup data from an attachment's stored metadata. * * @since 3.9.0 * * @param WP_Post $attachment The current attachment, provided for context. - * @param string $context The context. Accepts 'edit', 'display'. Default 'display'. + * @param string $context Optional. The context. Accepts 'edit', 'display'. Default 'display'. * @return array Key/value pairs of field keys to labels. */ function wp_get_attachment_id3_keys( $attachment, $context = 'display' ) { @@ -1479,14 +1512,14 @@ function wp_get_attachment_id3_keys( $attachment, $context = 'display' ) { return apply_filters( 'wp_get_attachment_id3_keys', $fields, $attachment, $context ); } /** - * The Audio shortcode. + * Builds the Audio shortcode output. * * This implements the functionality of the Audio Shortcode for displaying * WordPress mp3s in a post. * * @since 3.6.0 * - * @param array $attr { + * @param array $attr { * Attributes of the audio shortcode. * * @type string $src URL to the source of the audio file. Default empty. @@ -1497,7 +1530,7 @@ function wp_get_attachment_id3_keys( $attachment, $context = 'display' ) { * @type string $id The 'id' attribute for the `