Ticket #42677: cropper.diff

src/wp-includes/js/media/controllers/cropper.js

@@ -4 +4 @@
 /**
  * wp.media.controller.Cropper
  *
- * A state for cropping an image.
+ * A class for cropping an image when called from the header media customization panel.
  *
  * @memberOf wp.media.controller
  *
@@ -26 +26 @@
                 doCropArgs: {}
         },
 
+        /**
+         * @summary Opens the crop image window.
+         *
+         * Shows the crop image window when called from the Add new image button.
+         *
+         * @since 4.2.0
+         *
+         * @returns {void}
+         */
         activate: function() {
                 this.frame.on( 'content:create:crop', this.createCropContent, this );
                 this.frame.on( 'close', this.removeCropper, this );
                 this.set('selection', new Backbone.Collection(this.frame._selection.single));
         },
 
+        /**
+         * @summary Changes the state of the toolbar window to browse mode.
+         *
+         * @since 4.2.0
+         *
+         * @returns {void}
+         */
         deactivate: function() {
                 this.frame.toolbar.mode('browse');
         },
 
+        /**
+         * @summary Creates the crop image window.
+         *
+         * Initialized when clicking on the Select and Crop button.
+         *
+         * @since 4.2.0
+         *
+         * @fires crop window
+         *
+         * @returns {void}
+         */
         createCropContent: function() {
                 this.cropperView = new wp.media.view.Cropper({
                         controller: this,
@@ -45 +72 @@
                 this.frame.content.set(this.cropperView);
 
         },
+
+        /**
+         * @summary Removes the image selection and closes the cropping window.
+         *
+         * @since 4.2.0
+         *
+         * @returns {void}
+         */
         removeCropper: function() {
                 this.imgSelect.cancelSelection();
                 this.imgSelect.setOptions({remove: true});
                 this.imgSelect.update();
                 this.cropperView.remove();
         },
+
+        /**
+         * @summary Checks if cropping can be skipped and creates crop toolbar accordingly.
+         *
+         * @since 4.2.0
+         *
+         * @returns {void}
+         */
         createCropToolbar: function() {
                 var canSkipCrop, toolbarOptions;
 
@@ -106 +149 @@
                 this.frame.toolbar.set( new wp.media.view.Toolbar(toolbarOptions) );
         },
 
+        /**
+         * @summary Creates an object with the image attachment and crop properties.
+         *
+         * @since 4.2.0
+         *
+         * @returns {$.promise} A jQuery promise with the custom header crop details.
+         */
         doCrop: function( attachment ) {
                 return wp.ajax.post( 'custom-header-crop', _.extend(
                         {},