Make WordPress Core


Ignore:
Timestamp:
01/29/2020 12:43:23 AM (7 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.