Make WordPress Core


Ignore:
Timestamp:
01/29/2020 12:43:23 AM (4 years ago)
Author:
SergeyBiryukov
Message:

Docs: Improve inline comments per the documentation standards.

Includes minor code layout fixes for better readability.

See #48303.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/media.php

    r47060 r47122  
    7474        $max_width  = intval( get_option( 'thumbnail_size_w' ) );
    7575        $max_height = intval( get_option( 'thumbnail_size_h' ) );
    76         // last chance thumbnail size defaults
     76        // Last chance thumbnail size defaults.
    7777        if ( ! $max_width && ! $max_height ) {
    7878            $max_width  = 128;
     
    110110            $max_width = min( intval( $content_width ), $max_width );
    111111        }
    112     } else { // $size == 'full' has no constraint
     112    } else { // $size === 'full' has no constraint.
    113113        $max_width  = $width;
    114114        $max_height = $height;
     
    231231    }
    232232
    233     // try for a new style intermediate size
     233    // Try for a new style intermediate size.
    234234    $intermediate = image_get_intermediate_size( $id, $size );
    235235
     
    240240        $is_intermediate = true;
    241241    } elseif ( $size === 'thumbnail' ) {
    242         // fall back to the old thumbnail
     242        // Fall back to the old thumbnail.
    243243        $thumb_file = wp_get_attachment_thumb_file( $id );
    244244        $info       = null;
     
    257257
    258258    if ( ! $width && ! $height && isset( $meta['width'], $meta['height'] ) ) {
    259         // any other type: use the real image
     259        // Any other type: use the real image.
    260260        $width  = $meta['width'];
    261261        $height = $meta['height'];
     
    263263
    264264    if ( $img_url ) {
    265         // we have the actual image size, but might need to further constrain it if content_width is narrower
     265        // We have the actual image size, but might need to further constrain it if content_width is narrower.
    266266        list( $width, $height ) = image_constrain_size_for_editor( $width, $height, $size );
    267267
     
    451451    }
    452452
    453     // Calculate the larger/smaller ratios
     453    // Calculate the larger/smaller ratios.
    454454    $smaller_ratio = min( $width_ratio, $height_ratio );
    455455    $larger_ratio  = max( $width_ratio, $height_ratio );
     
    467467    $h = max( 1, (int) round( $current_height * $ratio ) );
    468468
    469     // Sometimes, due to rounding, we'll end up with a result like this: 465x700 in a 177x177 box is 117x176... a pixel short
    470     // We also have issues with recursive calls resulting in an ever-changing result. Constraining to the result of a constraint should yield the original result.
    471     // Thus we look for dimensions that are one pixel shy of the max value and bump them up
     469    /*
     470     * Sometimes, due to rounding, we'll end up with a result like this:
     471     * 465x700 in a 177x177 box is 117x176... a pixel short.
     472     * We also have issues with recursive calls resulting in an ever-changing result.
     473     * Constraining to the result of a constraint should yield the original result.
     474     * Thus we look for dimensions that are one pixel shy of the max value and bump them up.
     475     */
    472476
    473477    // Note: $did_width means it is possible $smaller_ratio == $width_ratio.
    474478    if ( $did_width && $w === $max_width - 1 ) {
    475         $w = $max_width; // Round it up
     479        $w = $max_width; // Round it up.
    476480    }
    477481
    478482    // Note: $did_height means it is possible $smaller_ratio == $height_ratio.
    479483    if ( $did_height && $h === $max_height - 1 ) {
    480         $h = $max_height; // Round it up
     484        $h = $max_height; // Round it up.
    481485    }
    482486
     
    529533        return false;
    530534    }
    531     // at least one of dest_w or dest_h must be specific
     535    // At least one of $dest_w or $dest_h must be specific.
    532536    if ( $dest_w <= 0 && $dest_h <= 0 ) {
    533537        return false;
     
    572576
    573577    if ( $crop ) {
    574         // Crop the largest possible portion of the original image that we can size to $dest_w x $dest_h.
    575         // Note that the requested crop dimensions are used as a maximum bounding box for the original image.
    576         // If the original image's width or height is less than the requested width or height
    577         // only the greater one will be cropped.
    578         // For example when the original image is 600x300, and the requested crop dimensions are 400x400,
    579         // the resulting image will be 400x300.
     578        /*
     579         * Crop the largest possible portion of the original image that we can size to $dest_w x $dest_h.
     580         * Note that the requested crop dimensions are used as a maximum bounding box for the original image.
     581         * If the original image's width or height is less than the requested width or height
     582         * only the greater one will be cropped.
     583         * For example when the original image is 600x300, and the requested crop dimensions are 400x400,
     584         * the resulting image will be 400x300.
     585         */
    580586        $aspect_ratio = $orig_w / $orig_h;
    581587        $new_w        = min( $dest_w, $orig_w );
     
    822828    }
    823829
    824     // include the full filesystem path of the intermediate file
     830    // Include the full filesystem path of the intermediate file.
    825831    if ( empty( $data['path'] ) && ! empty( $data['file'] ) && ! empty( $imagedata['file'] ) ) {
    826832        $file_url     = wp_get_attachment_url( $post_id );
     
    945951 */
    946952function wp_get_attachment_image_src( $attachment_id, $size = 'thumbnail', $icon = false ) {
    947     // get a thumbnail or intermediate image if there is one
     953    // Get a thumbnail or intermediate image if there is one.
    948954    $image = image_downsize( $attachment_id, $size );
    949955    if ( ! $image ) {
     
    10901096
    10911097    if ( false !== strpos( $dirname, 'wp-content/uploads' ) ) {
    1092         // Get the directory name relative to the upload directory (back compat for pre-2.7 uploads)
     1098        // Get the directory name relative to the upload directory (back compat for pre-2.7 uploads).
    10931099        $dirname = substr( $dirname, strpos( $dirname, 'wp-content/uploads' ) + 18 );
    10941100        $dirname = ltrim( $dirname, '/' );
     
    17411747
    17421748    $html5 = current_theme_supports( 'html5', 'caption' );
    1743     // HTML5 captions never added the extra 10px to the image width
     1749    // HTML5 captions never added the extra 10px to the image width.
    17441750    $width = $html5 ? $atts['width'] : ( 10 + $atts['width'] );
    17451751
     
    22622268    }
    22632269
    2264     $outer = 22; // default padding and border of wrapper
     2270    $outer = 22; // Default padding and border of wrapper.
    22652271
    22662272    $default_width  = 640;
     
    22722278    $data = array(
    22732279        'type'         => $atts['type'],
    2274         // don't pass strings to JSON, will be truthy in JS
     2280        // Don't pass strings to JSON, will be truthy in JS.
    22752281        'tracklist'    => wp_validate_boolean( $atts['tracklist'] ),
    22762282        'tracknumbers' => wp_validate_boolean( $atts['tracknumbers'] ),
     
    26022608    );
    26032609
    2604     // These ones should just be omitted altogether if they are blank
     2610    // These ones should just be omitted altogether if they are blank.
    26052611    foreach ( array( 'loop', 'autoplay', 'preload' ) as $a ) {
    26062612        if ( empty( $html_atts[ $a ] ) ) {
     
    27552761
    27562762    if ( is_admin() ) {
    2757         // shrink the video so it isn't huge in the admin
     2763        // Shrink the video so it isn't huge in the admin.
    27582764        if ( $atts['width'] > $defaults_atts['width'] ) {
    27592765            $atts['height'] = round( ( $atts['height'] * $defaults_atts['width'] ) / $atts['width'] );
     
    27612767        }
    27622768    } else {
    2763         // if the video is bigger than the theme
     2769        // If the video is bigger than the theme.
    27642770        if ( ! empty( $content_width ) && $atts['width'] > $content_width ) {
    27652771            $atts['height'] = round( ( $atts['height'] * $content_width ) / $atts['width'] );
     
    28322838    }
    28332839
    2834     // Mediaelement has issues with some URL formats for Vimeo and YouTube, so
    2835     // update the URL to prevent the ME.js player from breaking.
     2840    // MediaElement.js has issues with some URL formats for Vimeo and YouTube,
     2841    // so update the URL to prevent the ME.js player from breaking.
    28362842    if ( 'mediaelement' === $library ) {
    28372843        if ( $is_youtube ) {
     
    28722878    );
    28732879
    2874     // These ones should just be omitted altogether if they are blank
     2880    // These ones should just be omitted altogether if they are blank.
    28752881    foreach ( array( 'poster', 'loop', 'autoplay', 'preload' ) as $a ) {
    28762882        if ( empty( $html_atts[ $a ] ) ) {
     
    31323138 * Create new GD image resource with transparency support
    31333139 *
    3134  * @todo: Deprecate if possible.
     3140 * @todo Deprecate if possible.
    31353141 *
    31363142 * @since 2.9.0
     
    33263332     */
    33273333    $defaults = array(
    3328         'file_data_name' => 'async-upload', // key passed to $_FILE.
     3334        'file_data_name' => 'async-upload', // Key passed to $_FILE.
    33293335        'url'            => admin_url( 'async-upload.php', 'relative' ),
    33303336        'filters'        => array(
     
    33343340    );
    33353341
    3336     // Currently only iOS Safari supports multiple files uploading but iOS 7.x has a bug that prevents uploading of videos
    3337     // when enabled. See #29602.
     3342    /*
     3343     * Currently only iOS Safari supports multiple files uploading,
     3344     * but iOS 7.x has a bug that prevents uploading of videos when enabled.
     3345     * See #29602.
     3346     */
    33383347    if ( wp_is_mobile() && strpos( $_SERVER['HTTP_USER_AGENT'], 'OS 7_' ) !== false &&
    33393348        strpos( $_SERVER['HTTP_USER_AGENT'], 'like Mac OS X' ) !== false ) {
     
    35123521        unset( $possible_sizes['full'] );
    35133522
    3514         // Loop through all potential sizes that may be chosen. Try to do this with some efficiency.
    3515         // First: run the image_downsize filter. If it returns something, we can use its data.
    3516         // If the filter does not return something, then image_downsize() is just an expensive
    3517         // way to check the image metadata, which we do second.
     3523        /*
     3524         * Loop through all potential sizes that may be chosen. Try to do this with some efficiency.
     3525         * First: run the image_downsize filter. If it returns something, we can use its data.
     3526         * If the filter does not return something, then image_downsize() is just an expensive way
     3527         * to check the image metadata, which we do second.
     3528         */
    35183529        foreach ( $possible_sizes as $size => $label ) {
    35193530
     
    36703681
    36713682    $props = array(
    3672         'link'  => get_option( 'image_default_link_type' ), // db default is 'file'
    3673         'align' => get_option( 'image_default_align' ), // empty default
    3674         'size'  => get_option( 'image_default_size' ),  // empty default
     3683        'link'  => get_option( 'image_default_link_type' ), // DB default is 'file'.
     3684        'align' => get_option( 'image_default_align' ),     // Empty default.
     3685        'size'  => get_option( 'image_default_size' ),      // Empty default.
    36753686    );
    36763687
     
    38413852
    38423853    $strings = array(
    3843         // Generic
     3854        // Generic.
    38443855        'mediaFrameDefaultTitle'      => __( 'Media' ),
    38453856        'url'                         => __( 'URL' ),
     
    38603871        'dragInfo'                    => __( 'Drag and drop to reorder media files.' ),
    38613872
    3862         // Upload
     3873        // Upload.
    38633874        'uploadFilesTitle'            => __( 'Upload Files' ),
    38643875        'uploadImagesTitle'           => __( 'Upload Images' ),
    38653876
    3866         // Library
     3877        // Library.
    38673878        'mediaLibraryTitle'           => __( 'Media Library' ),
    38683879        'insertMediaTitle'            => __( 'Add Media' ),
     
    38903901        'filterByType'                => __( 'Filter by type' ),
    38913902        'searchLabel'                 => __( 'Search' ),
    3892         'searchMediaLabel'            => __( 'Search Media' ), // backwards compatibility pre-5.3
    3893         'searchMediaPlaceholder'      => __( 'Search media items...' ), // placeholder (no ellipsis), backwards compatibility pre-5.3
     3903        'searchMediaLabel'            => __( 'Search Media' ),          // Backward compatibility pre-5.3.
     3904        'searchMediaPlaceholder'      => __( 'Search media items...' ), // Placeholder (no ellipsis), backward compatibility pre-5.3.
    38943905        'mediaFound'                  => __( 'Number of media items found: %d' ),
    38953906        'mediaFoundHasMoreResults'    => __( 'Number of media items displayed: %d. Scroll the page for more results.' ),
     
    38973908        'noMediaTryNewSearch'         => __( 'No media items found. Try a different search.' ),
    38983909
    3899         // Library Details
     3910        // Library Details.
    39003911        'attachmentDetails'           => __( 'Attachment Details' ),
    39013912
    3902         // From URL
     3913        // From URL.
    39033914        'insertFromUrlTitle'          => __( 'Insert from URL' ),
    39043915
    3905         // Featured Images
     3916        // Featured Images.
    39063917        'setFeaturedImageTitle'       => $post_type_object->labels->featured_image,
    39073918        'setFeaturedImage'            => $post_type_object->labels->set_featured_image,
    39083919
    3909         // Gallery
     3920        // Gallery.
    39103921        'createGalleryTitle'          => __( 'Create Gallery' ),
    39113922        'editGalleryTitle'            => __( 'Edit Gallery' ),
     
    39173928        'reverseOrder'                => __( 'Reverse order' ),
    39183929
    3919         // Edit Image
     3930        // Edit Image.
    39203931        'imageDetailsTitle'           => __( 'Image Details' ),
    39213932        'imageReplaceTitle'           => __( 'Replace Image' ),
     
    39233934        'editImage'                   => __( 'Edit Image' ),
    39243935
    3925         // Crop Image
     3936        // Crop Image.
    39263937        'chooseImage'                 => __( 'Choose Image' ),
    39273938        'selectAndCrop'               => __( 'Select and Crop' ),
     
    39343945        'cropError'                   => __( 'There has been an error cropping your image.' ),
    39353946
    3936         // Edit Audio
     3947        // Edit Audio.
    39373948        'audioDetailsTitle'           => __( 'Audio Details' ),
    39383949        'audioReplaceTitle'           => __( 'Replace Audio' ),
     
    39403951        'audioDetailsCancel'          => __( 'Cancel Edit' ),
    39413952
    3942         // Edit Video
     3953        // Edit Video.
    39433954        'videoDetailsTitle'           => __( 'Video Details' ),
    39443955        'videoReplaceTitle'           => __( 'Replace Video' ),
     
    39483959        'videoAddTrackTitle'          => __( 'Add Subtitles' ),
    39493960
    3950         // Playlist
     3961        // Playlist.
    39513962        'playlistDragInfo'            => __( 'Drag and drop to reorder tracks.' ),
    39523963        'createPlaylistTitle'         => __( 'Create Audio Playlist' ),
     
    39583969        'addToPlaylistTitle'          => __( 'Add to Audio Playlist' ),
    39593970
    3960         // Video Playlist
     3971        // Video Playlist.
    39613972        'videoPlaylistDragInfo'       => __( 'Drag and drop to reorder videos.' ),
    39623973        'createVideoPlaylistTitle'    => __( 'Create Video Playlist' ),
     
    39683979        'addToVideoPlaylistTitle'     => __( 'Add to Video Playlist' ),
    39693980
    3970         // Headings
     3981        // Headings.
    39713982        'filterAttachments'           => __( 'Filter Media' ),
    39723983        'attachmentsList'             => __( 'Media list' ),
     
    39954006    $strings['settings'] = $settings;
    39964007
    3997     // Ensure we enqueue media-editor first, that way media-views is
    3998     // registered internally before we try to localize it. see #24724.
     4008    // Ensure we enqueue media-editor first, that way media-views
     4009    // is registered internally before we try to localize it. See #24724.
    39994010    wp_enqueue_script( 'media-editor' );
    40004011    wp_localize_script( 'media-views', '_wpMediaViewsL10n', $strings );
     
    42864297    $image_path = parse_url( $path );
    42874298
    4288     //force the protocols to match if needed
     4299    // Force the protocols to match if needed.
    42894300    if ( isset( $image_path['scheme'] ) && ( $image_path['scheme'] !== $site_url['scheme'] ) ) {
    42904301        $path = str_replace( $image_path['scheme'], $site_url['scheme'], $path );
     
    44374448 */
    44384449function _wp_add_additional_image_sizes() {
    4439     // 2x medium_large size
     4450    // 2x medium_large size.
    44404451    add_image_size( '1536x1536', 1536, 1536 );
    4441     // 2x large size
     4452    // 2x large size.
    44424453    add_image_size( '2048x2048', 2048, 2048 );
    44434454}
Note: See TracChangeset for help on using the changeset viewer.