Changeset 42352 for trunk

Timestamp:

12/03/2017 06:46:29 PM (7 years ago)

Author:

adamsilverstein

Message:

Docs: Improve JSDocs for cropper.js.

Props manuelaugustin, bramheijmink.
Fixes #42677.

File:

• trunk/src/wp-includes/js/media/controllers/cropper.js (modified) (6 diffs)

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

@@ -5 +5 @@
  * 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
@@ -27 +27 @@
     },
 
+    /**
+     * @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 );
@@ -33 +42 @@
     },
 
+    /**
+     * @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({
@@ -46 +73 @@
 
     },
+
+    /**
+     * @summary Removes the image selection and closes the cropping window.
+     *
+     * @since 4.2.0
+     *
+     * @returns {void}
+     */
     removeCropper: function() {
         this.imgSelect.cancelSelection();
@@ -52 +87 @@
         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;
@@ -107 +150 @@
     },
 
+    /**
+     * @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(