WordPress.org

Make WordPress Core

Ticket #28408: 28408.patch

File 28408.patch, 19.2 KB (added by stevegrunwell, 5 years ago)

Clean up DocBlock formatting, add some missing arguments, global declarations, and @since tags.

  • src/wp-includes/media.php

     
    5959                // if no width is set, default to the theme content width if available
    6060        }
    6161        elseif ( $size == 'large' ) {
    62                 // We're inserting a large size image into the editor. If it's a really
    63                 // big image we'll scale it down to fit reasonably within the editor
    64                 // itself, and within the theme's content width if it's known. The user
    65                 // can resize it in the editor if they wish.
     62                /*
     63                 * We're inserting a large size image into the editor. If it's a really
     64                 * big image we'll scale it down to fit reasonably within the editor
     65                 * itself, and within the theme's content width if it's known. The user
     66                 * can resize it in the editor if they wish.
     67                 */
    6668                $max_width = intval(get_option('large_size_w'));
    6769                $max_height = intval(get_option('large_size_h'));
    6870                if ( intval($content_width) > 0 )
     
    109111 *
    110112 * @since 2.5.0
    111113 *
    112  * @param int|string $width Optional. Width attribute value.
     114 * @param int|string $width  Optional. Width attribute value.
    113115 * @param int|string $height Optional. Height attribute value.
    114116 * @return string HTML attributes for width and, or height.
    115117 */
     
    140142 *
    141143 * @since 2.5.0
    142144 *
    143  * @param int $id Attachment ID for image.
     145 * @param int          $id  Attachment ID for image.
    144146 * @param array|string $size Optional, default is 'medium'. Size of image, either array or string.
    145147 * @return bool|array False on failure, array on success.
    146148 */
     
    297299 *
    298300 * @since 2.5.0
    299301 *
    300  * @param int $id Attachment ID.
    301  * @param string $alt Image Description for the alt attribute.
     302 * @param int    $id    Attachment ID.
     303 * @param string $alt   Image Description for the alt attribute.
    302304 * @param string $title Image Description for the title attribute.
    303305 * @param string $align Part of the class name for aligning the image.
    304  * @param string $size Optional. Default is 'medium'.
     306 * @param string $size  Optional. The registered image size. Default is 'medium'.
    305307 * @return string HTML IMG element for given image attachment
    306308 */
    307309function get_image_tag($id, $alt, $title, $align, $size='medium') {
     
    352354 *
    353355 * @since 2.5.0
    354356 *
    355  * @param int $current_width Current width of the image.
     357 * @param int $current_width  Current width of the image.
    356358 * @param int $current_height Current height of the image.
    357  * @param int $max_width Optional. Maximum wanted width.
    358  * @param int $max_height Optional. Maximum wanted height.
     359 * @param int $max_width      Optional. Maximum wanted width.
     360 * @param int $max_height     Optional. Maximum wanted height.
    359361 * @return array First item is the width, the second item is the height.
    360362 */
    361363function wp_constrain_dimensions( $current_width, $current_height, $max_width=0, $max_height=0 ) {
     
    405407                $h = $max_height; // Round it up
    406408        }
    407409
     410        /**
     411         * Constrain image dimensions.
     412         *
     413         * @since 4.1
     414         *
     415         * @param array $dimensions     The image width and height
     416         * @param int   $current_width  The current width of the image.
     417         * @param int   $current_height The current height of the image.
     418         * @param int   $max_width      The maximum width permitted.
     419         * @param int   $max_height     The maximum height permitted.
     420         */
    408421        return apply_filters( 'wp_constrain_dimensions', array( $w, $h ), $current_width, $current_height, $max_width, $max_height );
    409422}
    410423
     
    531544 *
    532545 * @since 2.5.0
    533546 *
    534  * @param string $file File path.
    535  * @param int $width Image width.
    536  * @param int $height Image height.
    537  * @param bool $crop Optional, default is false. Whether to crop image to specified height and width or resize.
     547 * @param string $file   File path.
     548 * @param int    $width  Image width.
     549 * @param int    $height Image height.
     550 * @param bool   $crop   Optional, default is false. Whether to crop image to
     551 *                       specified height and width or resize.
    538552 * @return bool|array False, if no image was created. Metadata array on success.
    539553 */
    540554function image_make_intermediate_size( $file, $width, $height, $crop = false ) {
     
    576590 * @since 2.5.0
    577591 * @see add_image_size()
    578592 *
    579  * @param int $post_id Attachment ID for image.
    580  * @param array|string $size Optional, default is 'thumbnail'. Size of image, either array or string.
     593 * @param int          $post_id Attachment ID for image.
     594 * @param array|string $size    Optional, default is 'thumbnail'. Size of image,
     595 *                              either array or string.
    581596 * @return bool|array False on failure or array of file path, width, and height on success.
    582597 */
    583598function image_get_intermediate_size($post_id, $size='thumbnail') {
     
    631646}
    632647
    633648/**
    634  * Get the available image sizes
     649 * Get the available image sizes.
     650 *
    635651 * @since 3.0.0
    636  * @return array Returns a filtered array of image size strings
     652 *
     653 * @global $_wp_additional_image_sizes
     654 * @return array Returns a filtered array of image size strings.
    637655 */
    638656function get_intermediate_image_sizes() {
    639657        global $_wp_additional_image_sizes;
     
    659677 *
    660678 * @since 2.5.0
    661679 *
    662  * @param int $attachment_id Image attachment ID.
    663  * @param string $size Optional, default is 'thumbnail'.
    664  * @param bool $icon Optional, default is false. Whether it is an icon.
     680 * @param int    $attachment_id Image attachment ID.
     681 * @param string $size          Optional, default is 'thumbnail'.
     682 * @param bool   $icon          Optional, default is false. Whether it is an icon.
    665683 * @return bool|array Returns an array (url, width, height), or false, if no image is available.
    666684 */
    667685function wp_get_attachment_image_src($attachment_id, $size='thumbnail', $icon = false) {
     
    752770 * dynamically add/remove itself so as to only filter post thumbnails
    753771 *
    754772 * @since 2.9.0
     773 *
    755774 * @param array $attr Attributes including src, class, alt, title
    756775 * @return array
    757776 */
     
    793812 *
    794813 * @since 2.6.0
    795814 *
    796  * @param array $attr {
     815 * @param array  $attr {
    797816 *     Attributes of the caption shortcode.
    798817 *
    799818 *     @type string $id      ID of the div element for the caption.
     
    14011420add_shortcode( 'playlist', 'wp_playlist_shortcode' );
    14021421
    14031422/**
    1404  * Provide a No-JS Flash fallback as a last resort for audio / video
     1423 * Provide a No-JS Flash fallback as a last resort for audio / video.
    14051424 *
    14061425 * @since 3.6.0
    14071426 *
    1408  * @param string $url
    1409  * @return string Fallback HTML
     1427 * @param string $url The media element URL.
     1428 * @return string Fallback HTML.
    14101429 */
    14111430function wp_mediaelement_fallback( $url ) {
    14121431        /**
     
    14241443 * Return a filtered list of WP-supported audio formats.
    14251444 *
    14261445 * @since 3.6.0
    1427  * @return array
     1446 *
     1447 * @return array Supported audio formats.
    14281448 */
    14291449function wp_get_audio_extensions() {
    14301450        /**
     
    14441464 * @since 3.9.0
    14451465 *
    14461466 * @param WP_Post $attachment The current attachment, provided for context.
    1447  * @param string  $context    The context. Accepts 'edit', 'display'. Default 'display'.
     1467 * @param string  $context    Optional. The context. Accepts 'edit', 'display'. Default 'display'.
    14481468 * @return array Key/value pairs of field keys to labels.
    14491469 */
    14501470function wp_get_attachment_id3_keys( $attachment, $context = 'display' ) {
     
    14811501 *
    14821502 * @since 3.6.0
    14831503 *
    1484  * @param array $attr {
     1504 * @param array  $attr {
    14851505 *     Attributes of the audio shortcode.
    14861506 *
    14871507 *     @type string $src      URL to the source of the audio file. Default empty.
     
    16481668add_shortcode( 'audio', 'wp_audio_shortcode' );
    16491669
    16501670/**
    1651  * Return a filtered list of WP-supported video formats
     1671 * Return a filtered list of WP-supported video formats.
    16521672 *
    16531673 * @since 3.6.0
    1654  * @return array
     1674 *
     1675 * @return array Supported video formats.
    16551676 */
    16561677function wp_get_video_extensions() {
    16571678        /**
     
    16731694 *
    16741695 * @since 3.6.0
    16751696 *
    1676  * @param array $attr {
     1697 * @param array  $attr {
    16771698 *     Attributes of the shortcode.
    16781699 *
    16791700 *     @type string $src      URL to the source of the video file. Default empty.
     
    18931914 * Display previous image link that has the same post parent.
    18941915 *
    18951916 * @since 2.5.0
     1917 * @see adjacent_image_link()
     1918 *
    18961919 * @param string $size Optional, default is 'thumbnail'. Size of image, either array or string. 0 or 'none' will default to post_title or $text;
    18971920 * @param string $text Optional, default is false. If included, link will reflect $text variable.
    18981921 * @return string HTML content.
     
    19051928 * Display next image link that has the same post parent.
    19061929 *
    19071930 * @since 2.5.0
     1931 * @see adjacent_image_link()
     1932 *
    19081933 * @param string $size Optional, default is 'thumbnail'. Size of image, either array or string. 0 or 'none' will default to post_title or $text;
    19091934 * @param string $text Optional, default is false. If included, link will reflect $text variable.
    19101935 * @return string HTML content.
     
    19211946 * @since 2.5.0
    19221947 *
    19231948 * @param bool $prev Optional. Default is true to display previous link, false for next.
     1949 * @param str  $size Optional. The image size. Default is 'thumbnail'.
     1950 * @param bool $text Optional. If string, then will be link text. Default is false.
     1951 * @return string The adjacent image link.
    19241952 */
    19251953function adjacent_image_link($prev = true, $size = 'thumbnail', $text = false) {
    19261954        $post = get_post();
     
    20092037 * @since 3.5.0
    20102038 * @see get_attachment_taxonomies()
    20112039 *
    2012  * @param string $output The type of output to return, either taxonomy 'names' or 'objects'. 'names' is the default.
     2040 * @param string $output The type of output to return, either taxonomy 'names' or 'objects'.
     2041 *                       'names' is the default.
    20132042 * @return array The names of all taxonomy of $object_type.
    20142043 */
    20152044function get_taxonomies_for_attachments( $output = 'names' ) {
     
    20312060
    20322061/**
    20332062 * Create new GD image resource with transparency support
    2034  * @TODO: Deprecate if possible.
    20352063 *
     2064 * @todo: Deprecate if possible.
     2065 *
    20362066 * @since 2.9.0
    20372067 *
    2038  * @param int $width Image width
    2039  * @param int $height Image height
    2040  * @return resource resource
     2068 * @param int $width  Image width.
     2069 * @param int $height Image height.
     2070 * @return resource The GD image resource.
    20412071 */
    20422072function wp_imagecreatetruecolor($width, $height) {
    20432073        $img = imagecreatetruecolor($width, $height);
     
    20552085 * @see WP_Embed::register_handler()
    20562086 *
    20572087 * @global WP_Embed $wp_embed
    2058  * @param string   $id
    2059  * @param string   $regex
    2060  * @param callable $callback
    2061  * @param int      $priority
     2088 * @param string   $id       An internal ID/name for the handler. Needs to be unique.
     2089 * @param string   $regex    The regex that will be used to see if this handler should be used for a URL.
     2090 * @param callback $callback The callback function that will be called if the regex is matched.
     2091 * @param int      $priority Optional. Used to specify the order in which the registered handlers will
     2092 *                           be tested (default: 10).
    20622093 */
    20632094function wp_embed_register_handler( $id, $regex, $callback, $priority = 10 ) {
    20642095        global $wp_embed;
     
    20722103 * @see WP_Embed::unregister_handler()
    20732104 *
    20742105 * @global WP_Embed $wp_embed
    2075  * @param string $id
    2076  * @param int    $priority
     2106 * @param string $id       The handler ID that should be removed.
     2107 * @param int    $priority Optional. The priority of the handler to be removed (default: 10).
    20772108 */
    20782109function wp_embed_unregister_handler( $id, $priority = 10 ) {
    20792110        global $wp_embed;
     
    21212152 * Based on a supplied width/height example, return the biggest possible dimensions based on the max width/height.
    21222153 *
    21232154 * @since 2.9.0
     2155 * @see wp_constrain_dimensions()
    21242156 *
    2125  * @param int $example_width The width of an example embed.
     2157 * @param int $example_width  The width of an example embed.
    21262158 * @param int $example_height The height of an example embed.
    2127  * @param int $max_width The maximum allowed width.
    2128  * @param int $max_height The maximum allowed height.
     2159 * @param int $max_width      The maximum allowed width.
     2160 * @param int $max_height     The maximum allowed height.
    21292161 * @return array The maximum possible width and height based on the example ratio.
    21302162 */
    21312163function wp_expand_dimensions( $example_width, $example_height, $max_width, $max_height ) {
     
    21432175 * @since 2.9.0
    21442176 * @see WP_oEmbed
    21452177 *
    2146  * @param string $url The URL that should be embedded.
    2147  * @param array $args Additional arguments and parameters.
     2178 * @param string $url  The URL that should be embedded.
     2179 * @param array  $args Additional arguments and parameters.
    21482180 * @return false|string False on failure or the embed HTML on success.
    21492181 */
    21502182function wp_oembed_get( $url, $args = '' ) {
     
    21592191 * @since 2.9.0
    21602192 * @see WP_oEmbed
    21612193 *
    2162  * @param string $format The format of URL that this provider can handle. You can use asterisks as wildcards.
    2163  * @param string $provider The URL to the oEmbed provider.
    2164  * @param boolean $regex Whether the $format parameter is in a regex format.
     2194 * @param string  $format  The format of URL that this provider can handle. You can use asterisks as wildcards.
     2195 * @param string  $provider The URL to the oEmbed provider.
     2196 * @param boolean $regex    Whether the $format parameter is in a regex format.
    21652197 */
    21662198function wp_oembed_add_provider( $format, $provider, $regex = false ) {
    21672199        require_once( ABSPATH . WPINC . '/class-oembed.php' );
     
    21812213 * @see WP_oEmbed
    21822214 *
    21832215 * @param string $format The URL format for the oEmbed provider to remove.
     2216 * @return bool Was the provider removed successfully?
    21842217 */
    21852218function wp_oembed_remove_provider( $format ) {
    21862219        require_once( ABSPATH . WPINC . '/class-oembed.php' );
     
    22062239 * it hasn't, then it will load the embeds library.
    22072240 *
    22082241 * @since 2.9.0
     2242 * @see wp_embed_register_handler()
    22092243 */
    22102244function wp_maybe_load_embeds() {
    22112245        /**
     
    22502284 * @see WP_Embed::register_handler()
    22512285 * @see WP_Embed::shortcode()
    22522286 *
    2253  * @param array $matches The regex matches from the provided regex when calling {@link wp_embed_register_handler()}.
    2254  * @param array $attr Embed attributes.
    2255  * @param string $url The original URL that was matched by the regex.
    2256  * @param array $rawattr The original unmodified attributes.
     2287 * @param array  $matches The regex matches from the provided regex when calling {@link wp_embed_register_handler()}.
     2288 * @param array  $attr    Embed attributes.
     2289 * @param string $url     The original URL that was matched by the regex.
     2290 * @param array  $rawattr The original unmodified attributes.
    22572291 * @return string The embed HTML.
    22582292 */
    22592293function wp_embed_handler_googlevideo( $matches, $attr, $url, $rawattr ) {
     
    22962330function wp_embed_handler_youtube( $matches, $attr, $url, $rawattr ) {
    22972331        global $wp_embed;
    22982332        $embed = $wp_embed->autoembed( "https://youtube.com/watch?v={$matches[2]}" );
     2333
    22992334        /**
    23002335         * Filter the YoutTube embed output.
    23012336         *
     
    23432378 *
    23442379 * @since 3.6.0
    23452380 *
    2346  * @param array $matches The regex matches from the provided regex when calling {@link wp_embed_register_handler()}.
    2347  * @param array $attr Embed attributes.
    2348  * @param string $url The original URL that was matched by the regex.
    2349  * @param array $rawattr The original unmodified attributes.
     2381 * @param array  $matches The regex matches from the provided regex when calling {@link wp_embed_register_handler()}.
     2382 * @param array  $attr    Embed attributes.
     2383 * @param string $url     The original URL that was matched by the regex.
     2384 * @param array  $rawattr The original unmodified attributes.
    23502385 * @return string The embed HTML.
    23512386 */
    23522387function wp_embed_handler_video( $matches, $attr, $url, $rawattr ) {
     
    24172452 * Returns a WP_Image_Editor instance and loads file into it.
    24182453 *
    24192454 * @since 3.5.0
    2420  * @access public
     2455 * @see _wp_image_editor_choose()
    24212456 *
    2422  * @param string $path Path to file to load
    2423  * @param array $args Additional data. Accepts { 'mime_type'=>string, 'methods'=>{string, string, ...} }
    2424  * @return WP_Image_Editor|WP_Error
     2457 * @param string $path Path to the file to load.
     2458 * @param array  $args Additional data. Accepts { 'mime_type'=>string, 'methods'=>{string, string, ...} }.
     2459 * @return WP_Image_Editor|WP_Error The WP_Image_Editor object if successful, an WP_Error object otherwise.
    24252460 */
    24262461function wp_get_image_editor( $path, $args = array() ) {
    24272462        $args['path'] = $path;
     
    24542489 * Tests whether there is an editor that supports a given mime type or methods.
    24552490 *
    24562491 * @since 3.5.0
    2457  * @access public
     2492 * @see _wp_image_editor_choose()
    24582493 *
    24592494 * @param string|array $args Array of requirements. Accepts { 'mime_type'=>string, 'methods'=>{string, string, ...} }
    2460  * @return boolean true if an eligible editor is found; false otherwise
     2495 * @return boolean true if an eligible editor is found; false otherwise.
    24612496 */
    24622497function wp_image_editor_supports( $args = array() ) {
    24632498        return (bool) _wp_image_editor_choose( $args );
     
    25132548 * Prints default plupload arguments.
    25142549 *
    25152550 * @since 3.4.0
     2551 *
     2552 * @global $wp_scripts
    25162553 */
    25172554function wp_plupload_default_settings() {
    25182555        global $wp_scripts;
     
    27832820 * all media JS APIs.
    27842821 *
    27852822 * @since 3.5.0
     2823 *
     2824 * @global $content_width
     2825 * @global $wpdb
     2826 * @global $wp_locale
     2827 * @param array $args {
     2828 *              @type int|WP_Post A post object or ID.
     2829 * }
     2830 * @return array List of media view settings.
    27862831 */
    27872832function wp_enqueue_media( $args = array() ) {
    27882833
     
    31263171 * @since 3.6.0
    31273172 *
    31283173 * @param string $content A string which might contain media data.
    3129  * @param array $types array of media types: 'audio', 'video', 'object', 'embed', or 'iframe'
    3130  * @return array A list of found HTML media embeds
     3174 * @param array  $types   Optional. An array of media types: 'audio', 'video', 'object', 'embed',
     3175 *                        or 'iframe'. Defaults to null.
     3176 * @return array A list of found HTML media embeds.
    31313177 */
    31323178function get_media_embedded_in_content( $content, $types = null ) {
    31333179        $html = array();
     
    31553201 * @param int|WP_Post $post Optional. Post ID or object.
    31563202 * @param bool        $html Whether to return HTML or data in the array.
    31573203 * @return array A list of arrays, each containing gallery data and srcs parsed
    3158  *                       from the expanded shortcode.
     3204 *               from the expanded shortcode.
    31593205 */
    31603206function get_post_galleries( $post, $html = true ) {
    31613207        if ( ! $post = get_post( $post ) )
     
    32053251 * @since 3.6.0
    32063252 *
    32073253 * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global $post.
    3208  * @param bool        $html Whether to return HTML or data.
     3254 * @param bool        $html Optional. Whether to return HTML or data. Default is true.
    32093255 * @return string|array Gallery data and srcs parsed from the expanded shortcode.
    32103256 */
    32113257function get_post_gallery( $post = 0, $html = true ) {
     
    32313277 *
    32323278 * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global $post.
    32333279 * @return array A list of lists, each containing image srcs parsed.
    3234  *              from an expanded shortcode
     3280 *               from an expanded shortcode
    32353281 */
    32363282function get_post_galleries_images( $post = 0 ) {
    32373283        $galleries = get_post_galleries( $post, false );
     
    32823328 * @since 4.0.0
    32833329 *
    32843330 * @global wpdb $wpdb WordPress database abstraction object.
    3285  *
    32863331 * @param string $url The URL to resolve.
    32873332 * @return int The found post ID.
    32883333 */
     
    33123357 * @since 4.0.0
    33133358 *
    33143359 * @global $wp_version
    3315  *
    33163360 * @return array The relevant CSS file URLs.
    33173361 */
    33183362function wpview_media_sandbox_styles() {