Changeset 47122 for trunk/src/wp-includes/media.php

Timestamp:

01/29/2020 12:43:23 AM (5 years ago)

Author:

SergeyBiryukov

Message:

Docs: Improve inline comments per the documentation standards.

Includes minor code layout fixes for better readability.

See #48303.

File:

• trunk/src/wp-includes/media.php (modified) (40 diffs)

trunk/src/wp-includes/media.php

@@ -74 +74 @@
         $max_width  = intval( get_option( 'thumbnail_size_w' ) );
         $max_height = intval( get_option( 'thumbnail_size_h' ) );
-        // last chance thumbnail size defaults
+        // Last chance thumbnail size defaults.
         if ( ! $max_width && ! $max_height ) {
             $max_width  = 128;
@@ -110 +110 @@
             $max_width = min( intval( $content_width ), $max_width );
         }
-    } else { // $size == 'full' has no constraint
+    } else { // $size === 'full' has no constraint.
         $max_width  = $width;
         $max_height = $height;
@@ -231 +231 @@
     }
 
-    // try for a new style intermediate size
+    // Try for a new style intermediate size.
     $intermediate = image_get_intermediate_size( $id, $size );
 
@@ -240 +240 @@
         $is_intermediate = true;
     } elseif ( $size === 'thumbnail' ) {
-        // fall back to the old thumbnail
+        // Fall back to the old thumbnail.
         $thumb_file = wp_get_attachment_thumb_file( $id );
         $info       = null;
@@ -257 +257 @@
 
     if ( ! $width && ! $height && isset( $meta['width'], $meta['height'] ) ) {
-        // any other type: use the real image
+        // Any other type: use the real image.
         $width  = $meta['width'];
         $height = $meta['height'];
@@ -263 +263 @@
 
     if ( $img_url ) {
-        // we have the actual image size, but might need to further constrain it if content_width is narrower
+        // We have the actual image size, but might need to further constrain it if content_width is narrower.
         list( $width, $height ) = image_constrain_size_for_editor( $width, $height, $size );
 
@@ -451 +451 @@
     }
 
-    // Calculate the larger/smaller ratios
+    // Calculate the larger/smaller ratios.
     $smaller_ratio = min( $width_ratio, $height_ratio );
     $larger_ratio  = max( $width_ratio, $height_ratio );
@@ -467 +467 @@
     $h = max( 1, (int) round( $current_height * $ratio ) );
 
-    // Sometimes, due to rounding, we'll end up with a result like this: 465x700 in a 177x177 box is 117x176... a pixel short
-    // 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.
-    // Thus we look for dimensions that are one pixel shy of the max value and bump them up
+    /*
+     * Sometimes, due to rounding, we'll end up with a result like this:
+     * 465x700 in a 177x177 box is 117x176... a pixel short.
+     * 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.
+     * Thus we look for dimensions that are one pixel shy of the max value and bump them up.
+     */
 
     // Note: $did_width means it is possible $smaller_ratio == $width_ratio.
     if ( $did_width && $w === $max_width - 1 ) {
-        $w = $max_width; // Round it up
+        $w = $max_width; // Round it up.
     }
 
     // Note: $did_height means it is possible $smaller_ratio == $height_ratio.
     if ( $did_height && $h === $max_height - 1 ) {
-        $h = $max_height; // Round it up
+        $h = $max_height; // Round it up.
     }
 
@@ -529 +533 @@
         return false;
     }
-    // at least one of dest_w or dest_h must be specific
+    // At least one of $dest_w or $dest_h must be specific.
     if ( $dest_w <= 0 && $dest_h <= 0 ) {
         return false;
@@ -572 +576 @@
 
     if ( $crop ) {
-        // Crop the largest possible portion of the original image that we can size to $dest_w x $dest_h.
-        // Note that the requested crop dimensions are used as a maximum bounding box for the original image.
-        // If the original image's width or height is less than the requested width or height
-        // only the greater one will be cropped.
-        // For example when the original image is 600x300, and the requested crop dimensions are 400x400,
-        // the resulting image will be 400x300.
+        /*
+         * Crop the largest possible portion of the original image that we can size to $dest_w x $dest_h.
+         * Note that the requested crop dimensions are used as a maximum bounding box for the original image.
+         * If the original image's width or height is less than the requested width or height
+         * only the greater one will be cropped.
+         * For example when the original image is 600x300, and the requested crop dimensions are 400x400,
+         * the resulting image will be 400x300.
+         */
         $aspect_ratio = $orig_w / $orig_h;
         $new_w        = min( $dest_w, $orig_w );
@@ -822 +828 @@
     }
 
-    // include the full filesystem path of the intermediate file
+    // Include the full filesystem path of the intermediate file.
     if ( empty( $data['path'] ) && ! empty( $data['file'] ) && ! empty( $imagedata['file'] ) ) {
         $file_url     = wp_get_attachment_url( $post_id );
@@ -945 +951 @@
  */
 function wp_get_attachment_image_src( $attachment_id, $size = 'thumbnail', $icon = false ) {
-    // get a thumbnail or intermediate image if there is one
+    // Get a thumbnail or intermediate image if there is one.
     $image = image_downsize( $attachment_id, $size );
     if ( ! $image ) {
@@ -1090 +1096 @@
 
     if ( false !== strpos( $dirname, 'wp-content/uploads' ) ) {
-        // Get the directory name relative to the upload directory (back compat for pre-2.7 uploads)
+        // Get the directory name relative to the upload directory (back compat for pre-2.7 uploads).
         $dirname = substr( $dirname, strpos( $dirname, 'wp-content/uploads' ) + 18 );
         $dirname = ltrim( $dirname, '/' );
@@ -1741 +1747 @@
 
     $html5 = current_theme_supports( 'html5', 'caption' );
-    // HTML5 captions never added the extra 10px to the image width
+    // HTML5 captions never added the extra 10px to the image width.
     $width = $html5 ? $atts['width'] : ( 10 + $atts['width'] );
 
@@ -2262 +2268 @@
     }
 
-    $outer = 22; // default padding and border of wrapper
+    $outer = 22; // Default padding and border of wrapper.
 
     $default_width  = 640;
@@ -2272 +2278 @@
     $data = array(
         'type'         => $atts['type'],
-        // don't pass strings to JSON, will be truthy in JS
+        // Don't pass strings to JSON, will be truthy in JS.
         'tracklist'    => wp_validate_boolean( $atts['tracklist'] ),
         'tracknumbers' => wp_validate_boolean( $atts['tracknumbers'] ),
@@ -2602 +2608 @@
     );
 
-    // These ones should just be omitted altogether if they are blank
+    // These ones should just be omitted altogether if they are blank.
     foreach ( array( 'loop', 'autoplay', 'preload' ) as $a ) {
         if ( empty( $html_atts[ $a ] ) ) {
@@ -2755 +2761 @@
 
     if ( is_admin() ) {
-        // shrink the video so it isn't huge in the admin
+        // Shrink the video so it isn't huge in the admin.
         if ( $atts['width'] > $defaults_atts['width'] ) {
             $atts['height'] = round( ( $atts['height'] * $defaults_atts['width'] ) / $atts['width'] );
@@ -2761 +2767 @@
         }
     } else {
-        // if the video is bigger than the theme
+        // If the video is bigger than the theme.
         if ( ! empty( $content_width ) && $atts['width'] > $content_width ) {
             $atts['height'] = round( ( $atts['height'] * $content_width ) / $atts['width'] );
@@ -2832 +2838 @@
     }
 
-    // Mediaelement has issues with some URL formats for Vimeo and YouTube, so
-    // update the URL to prevent the ME.js player from breaking.
+    // MediaElement.js has issues with some URL formats for Vimeo and YouTube,
+    // so update the URL to prevent the ME.js player from breaking.
     if ( 'mediaelement' === $library ) {
         if ( $is_youtube ) {
@@ -2872 +2878 @@
     );
 
-    // These ones should just be omitted altogether if they are blank
+    // These ones should just be omitted altogether if they are blank.
     foreach ( array( 'poster', 'loop', 'autoplay', 'preload' ) as $a ) {
         if ( empty( $html_atts[ $a ] ) ) {
@@ -3132 +3138 @@
  * Create new GD image resource with transparency support
  *
- * @todo: Deprecate if possible.
+ * @todo Deprecate if possible.
  *
  * @since 2.9.0
@@ -3326 +3332 @@
      */
     $defaults = array(
-        'file_data_name' => 'async-upload', // key passed to $_FILE.
+        'file_data_name' => 'async-upload', // Key passed to $_FILE.
         'url'            => admin_url( 'async-upload.php', 'relative' ),
         'filters'        => array(
@@ -3334 +3340 @@
     );
 
-    // Currently only iOS Safari supports multiple files uploading but iOS 7.x has a bug that prevents uploading of videos
-    // when enabled. See #29602.
+    /*
+     * Currently only iOS Safari supports multiple files uploading,
+     * but iOS 7.x has a bug that prevents uploading of videos when enabled.
+     * See #29602.
+     */
     if ( wp_is_mobile() && strpos( $_SERVER['HTTP_USER_AGENT'], 'OS 7_' ) !== false &&
         strpos( $_SERVER['HTTP_USER_AGENT'], 'like Mac OS X' ) !== false ) {
@@ -3512 +3521 @@
         unset( $possible_sizes['full'] );
 
-        // Loop through all potential sizes that may be chosen. Try to do this with some efficiency.
-        // First: run the image_downsize filter. If it returns something, we can use its data.
-        // If the filter does not return something, then image_downsize() is just an expensive
-        // way to check the image metadata, which we do second.
+        /*
+         * Loop through all potential sizes that may be chosen. Try to do this with some efficiency.
+         * First: run the image_downsize filter. If it returns something, we can use its data.
+         * If the filter does not return something, then image_downsize() is just an expensive way
+         * to check the image metadata, which we do second.
+         */
         foreach ( $possible_sizes as $size => $label ) {
 
@@ -3670 +3681 @@
 
     $props = array(
-        'link'  => get_option( 'image_default_link_type' ), // db default is 'file'
-        'align' => get_option( 'image_default_align' ), // empty default
-        'size'  => get_option( 'image_default_size' ),  // empty default
+        'link'  => get_option( 'image_default_link_type' ), // DB default is 'file'.
+        'align' => get_option( 'image_default_align' ),     // Empty default.
+        'size'  => get_option( 'image_default_size' ),      // Empty default.
     );
 
@@ -3841 +3852 @@
 
     $strings = array(
-        // Generic
+        // Generic.
         'mediaFrameDefaultTitle'      => __( 'Media' ),
         'url'                         => __( 'URL' ),
@@ -3860 +3871 @@
         'dragInfo'                    => __( 'Drag and drop to reorder media files.' ),
 
-        // Upload
+        // Upload.
         'uploadFilesTitle'            => __( 'Upload Files' ),
         'uploadImagesTitle'           => __( 'Upload Images' ),
 
-        // Library
+        // Library.
         'mediaLibraryTitle'           => __( 'Media Library' ),
         'insertMediaTitle'            => __( 'Add Media' ),
@@ -3890 +3901 @@
         'filterByType'                => __( 'Filter by type' ),
         'searchLabel'                 => __( 'Search' ),
-        'searchMediaLabel'            => __( 'Search Media' ), // backwards compatibility pre-5.3
-        'searchMediaPlaceholder'      => __( 'Search media items...' ), // placeholder (no ellipsis), backwards compatibility pre-5.3
+        'searchMediaLabel'            => __( 'Search Media' ),          // Backward compatibility pre-5.3.
+        'searchMediaPlaceholder'      => __( 'Search media items...' ), // Placeholder (no ellipsis), backward compatibility pre-5.3.
         'mediaFound'                  => __( 'Number of media items found: %d' ),
         'mediaFoundHasMoreResults'    => __( 'Number of media items displayed: %d. Scroll the page for more results.' ),
@@ -3897 +3908 @@
         'noMediaTryNewSearch'         => __( 'No media items found. Try a different search.' ),
 
-        // Library Details
+        // Library Details.
         'attachmentDetails'           => __( 'Attachment Details' ),
 
-        // From URL
+        // From URL.
         'insertFromUrlTitle'          => __( 'Insert from URL' ),
 
-        // Featured Images
+        // Featured Images.
         'setFeaturedImageTitle'       => $post_type_object->labels->featured_image,
         'setFeaturedImage'            => $post_type_object->labels->set_featured_image,
 
-        // Gallery
+        // Gallery.
         'createGalleryTitle'          => __( 'Create Gallery' ),
         'editGalleryTitle'            => __( 'Edit Gallery' ),
@@ -3917 +3928 @@
         'reverseOrder'                => __( 'Reverse order' ),
 
-        // Edit Image
+        // Edit Image.
         'imageDetailsTitle'           => __( 'Image Details' ),
         'imageReplaceTitle'           => __( 'Replace Image' ),
@@ -3923 +3934 @@
         'editImage'                   => __( 'Edit Image' ),
 
-        // Crop Image
+        // Crop Image.
         'chooseImage'                 => __( 'Choose Image' ),
         'selectAndCrop'               => __( 'Select and Crop' ),
@@ -3934 +3945 @@
         'cropError'                   => __( 'There has been an error cropping your image.' ),
 
-        // Edit Audio
+        // Edit Audio.
         'audioDetailsTitle'           => __( 'Audio Details' ),
         'audioReplaceTitle'           => __( 'Replace Audio' ),
@@ -3940 +3951 @@
         'audioDetailsCancel'          => __( 'Cancel Edit' ),
 
-        // Edit Video
+        // Edit Video.
         'videoDetailsTitle'           => __( 'Video Details' ),
         'videoReplaceTitle'           => __( 'Replace Video' ),
@@ -3948 +3959 @@
         'videoAddTrackTitle'          => __( 'Add Subtitles' ),
 
-        // Playlist
+        // Playlist.
         'playlistDragInfo'            => __( 'Drag and drop to reorder tracks.' ),
         'createPlaylistTitle'         => __( 'Create Audio Playlist' ),
@@ -3958 +3969 @@
         'addToPlaylistTitle'          => __( 'Add to Audio Playlist' ),
 
-        // Video Playlist
+        // Video Playlist.
         'videoPlaylistDragInfo'       => __( 'Drag and drop to reorder videos.' ),
         'createVideoPlaylistTitle'    => __( 'Create Video Playlist' ),
@@ -3968 +3979 @@
         'addToVideoPlaylistTitle'     => __( 'Add to Video Playlist' ),
 
-        // Headings
+        // Headings.
         'filterAttachments'           => __( 'Filter Media' ),
         'attachmentsList'             => __( 'Media list' ),
@@ -3995 +4006 @@
     $strings['settings'] = $settings;
 
-    // Ensure we enqueue media-editor first, that way media-views is
-    // registered internally before we try to localize it. see #24724.
+    // Ensure we enqueue media-editor first, that way media-views
+    // is registered internally before we try to localize it. See #24724.
     wp_enqueue_script( 'media-editor' );
     wp_localize_script( 'media-views', '_wpMediaViewsL10n', $strings );
@@ -4286 +4297 @@
     $image_path = parse_url( $path );
 
-    //force the protocols to match if needed
+    // Force the protocols to match if needed.
     if ( isset( $image_path['scheme'] ) && ( $image_path['scheme'] !== $site_url['scheme'] ) ) {
         $path = str_replace( $image_path['scheme'], $site_url['scheme'], $path );
@@ -4437 +4448 @@
  */
 function _wp_add_additional_image_sizes() {
-    // 2x medium_large size
+    // 2x medium_large size.
     add_image_size( '1536x1536', 1536, 1536 );
-    // 2x large size
+    // 2x large size.
     add_image_size( '2048x2048', 2048, 2048 );
 }