Changeset 42415

Timestamp:

12/21/2017 02:26:17 PM (7 years ago)

Author:

atimmer

Message:

Docs: Improve JSDoc for media/views/attachments.js.

Props maartenleenders, herregroen, jipmoors, ireneyoast.
Fixes #42832.

Location:

trunk/src/wp-includes/js

Files:

• media-views.js (modified) (20 diffs)
• media/views/attachments.js (modified) (20 diffs)

trunk/src/wp-includes/js/media-views.js

@@ -6621 +6621 @@
     Attachments;
 
-/**
- * wp.media.view.Attachments
- *
- * @memberOf wp.media.view
- *
- * @class
- * @augments wp.media.View
- * @augments wp.Backbone.View
- * @augments Backbone.View
- */
 Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{
     tagName:   'ul',
@@ -6639 +6629 @@
     },
 
+    /**
+     * Represents the overview of attachments in the Media Library.
+     *
+     * The constructor binds events to the collection this view represents when
+     * adding or removing attachments or resetting the entire collection.
+     *
+     * @since 3.5.0
+     *
+     * @constructs
+     * @memberof wp.media.view
+     *
+     * @augments wp.media.View
+     *
+     * @listens collection:add
+     * @listens collection:remove
+     * @listens collection:reset
+     * @listens controller:library:selection:add
+     * @listens scrollElement:scroll
+     * @listens this:ready
+     * @listens controller:open
+     */
     initialize: function() {
         this.el.id = _.uniqueId('__attachments-view-');
 
+        /**
+         * @param refreshSensitivity The time in milliseconds to throttle the scroll
+         *                           handler.
+         * @param refreshThreshold   The amount of pixels that should be scrolled before
+         *                           loading more attachments from the server.
+         * @param AttachmentView     The view class to be used for models in the
+         *                           collection.
+         * @param sortable           A jQuery sortable options object
+         *                           ( http://api.jqueryui.com/sortable/ ).
+         * @param resize             A boolean indicating whether or not to listen to
+         *                           resize events.
+         * @param idealColumnWidth   The width in pixels which a column should have when
+         *                           calculating the total number of columns.
+         */
         _.defaults( this.options, {
             refreshSensitivity: wp.media.isTouchDevice ? 300 : 200,
@@ -6661 +6686 @@
         }, this );
 
+        /*
+         * Find the view to be removed, delete it and call the remove function to clear
+         * any set event handlers.
+         */
         this.collection.on( 'remove', function( attachment ) {
             var view = this._viewsByCid[ attachment.cid ];
@@ -6688 +6717 @@
             this.controller.on( 'open', this.setColumns );
 
-            // Call this.setColumns() after this view has been rendered in the DOM so
-            // attachments get proper width applied.
+            /*
+             * Call this.setColumns() after this view has been rendered in the
+             * DOM so attachments get proper width applied.
+             */
             _.defer( this.setColumns, this );
         }
     },
 
+    /**
+     * Listens to the resizeEvent on the window.
+     *
+     * Adjusts the amount of columns accordingly. First removes any existing event
+     * handlers to prevent duplicate listeners.
+     *
+     * @since 4.0.0
+     *
+     * @listens window:resize
+     *
+     * @returns {void}
+     */
     bindEvents: function() {
         this.$window.off( this.resizeEvent ).on( this.resizeEvent, _.debounce( this.setColumns, 50 ) );
     },
 
+    /**
+     * Focuses the first item in the collection.
+     *
+     * @since 4.0.0
+     *
+     * @returns {void}
+     */
     attachmentFocus: function() {
         this.$( 'li:first' ).focus();
     },
 
+    /**
+     * Restores focus to the selected item in the collection.
+     *
+     * @since 4.0.0
+     *
+     * @returns {void}
+     */
     restoreFocus: function() {
         this.$( 'li.selected:first' ).focus();
     },
 
+    /**
+     * Handles events for arrow key presses.
+     *
+     * Focuses the attachment in the direction of the used arrow key if it exists.
+     *
+     * @since 4.0.0
+     *
+     * @param {KeyboardEvent} event The keyboard event that triggered this function.
+     *
+     * @returns {void}
+     */
     arrowEvent: function( event ) {
         var attachments = this.$el.children( 'li' ),
@@ -6716 +6784 @@
         }
 
-        // Left arrow
+        // Left arrow = 37.
         if ( 37 === event.keyCode ) {
             if ( 0 === index ) {
@@ -6724 +6792 @@
         }
 
-        // Up arrow
+        // Up arrow = 38.
         if ( 38 === event.keyCode ) {
             if ( 1 === row ) {
@@ -6732 +6800 @@
         }
 
-        // Right arrow
+        // Right arrow = 39.
         if ( 39 === event.keyCode ) {
             if ( attachments.length === index ) {
@@ -6740 +6808 @@
         }
 
-        // Down arrow
+        // Down arrow = 40.
         if ( 40 === event.keyCode ) {
             if ( Math.ceil( attachments.length / perRow ) === row ) {
@@ -6749 +6817 @@
     },
 
+    /**
+     * Clears any set event handlers.
+     *
+     * @since 3.5.0
+     *
+     * @returns {void}
+     */
     dispose: function() {
         this.collection.props.off( null, null, this );
@@ -6755 +6830 @@
         }
 
-        /**
-         * call 'dispose' directly on the parent class
-         */
+        // Call 'dispose' directly on the parent class.
         View.prototype.dispose.apply( this, arguments );
     },
 
+    /**
+     * Calculates the amount of columns.
+     *
+     * Calculates the amount of columns and sets it on the data-columns attribute
+     * of .media-frame-content.
+     *
+     * @since 4.0.0
+     *
+     * @returns {void}
+     */
     setColumns: function() {
         var prev = this.columns,
@@ -6774 +6857 @@
     },
 
+    /**
+     * Initializes jQuery sortable on the attachment list.
+     *
+     * Fails gracefully if jQuery sortable doesn't exist or isn't passed in the
+     * options.
+     *
+     * @since 3.5.0
+     *
+     * @fires collection:reset
+     *
+     * @returns {void}
+     */
     initSortable: function() {
         var collection = this.collection;
@@ -6785 +6880 @@
             disabled: !! collection.comparator,
 
-            // Change the position of the attachment as soon as the
-            // mouse pointer overlaps a thumbnail.
+            /*
+             * Change the position of the attachment as soon as the mouse pointer overlaps a
+             * thumbnail.
+             */
             tolerance: 'pointer',
 
@@ -6794 +6891 @@
             },
 
-            // Update the model's index in the collection.
-            // Do so silently, as the view is already accurate.
+            /*
+             * Update the model's index in the collection. Do so silently, as the view
+             * is already accurate.
+             */
             update: function( event, ui ) {
                 var model = collection.at( ui.item.data('sortableIndexStart') ),
@@ -6819 +6918 @@
                 collection.trigger( 'reset', collection );
 
-                // If the collection is sorted by menu order,
-                // update the menu order.
+                // If the collection is sorted by menu order, update the menu order.
                 collection.saveMenuOrder();
             }
         }, this.options.sortable ) );
 
-        // If the `orderby` property is changed on the `collection`,
-        // check to see if we have a `comparator`. If so, disable sorting.
+        /*
+         * If the `orderby` property is changed on the `collection`, check to see if we
+         * have a `comparator`. If so, disable sorting.
+         */
         collection.props.on( 'change:orderby', function() {
             this.$el.sortable( 'option', 'disabled', !! collection.comparator );
@@ -6835 +6935 @@
     },
 
+    /**
+     * Disables jQuery sortable if collection has a comparator or collection.orderby
+     * equals menuOrder.
+     *
+     * @since 3.5.0
+     *
+     * @returns {void}
+     */
     refreshSortable: function() {
         if ( ! this.options.sortable || ! $.fn.sortable ) {
@@ -6840 +6948 @@
         }
 
-        // If the `collection` has a `comparator`, disable sorting.
         var collection = this.collection,
             orderby = collection.props.get('orderby'),
@@ -6849 +6956 @@
 
     /**
+     * Creates a new view for an attachment and adds it to _viewsByCid.
+     *
+     * @since 3.5.0
+     *
      * @param {wp.media.model.Attachment} attachment
-     * @returns {wp.media.View}
+     *
+     * @returns {wp.media.View} The created view.
      */
     createAttachmentView: function( attachment ) {
@@ -6863 +6975 @@
     },
 
+    /**
+     * Prepares view for display.
+     *
+     * Creates views for every attachment in collection if the collection is not
+     * empty, otherwise clears all views and loads more attachments.
+     *
+     * @since 3.5.0
+     *
+     * @returns {void}
+     */
     prepare: function() {
-        // Create all of the Attachment views, and replace
-        // the list in a single DOM operation.
         if ( this.collection.length ) {
             this.views.set( this.collection.map( this.createAttachmentView, this ) );
-
-        // If there are no elements, clear the views and load some.
         } else {
             this.views.unset();
@@ -6876 +6994 @@
     },
 
+    /**
+     * Triggers the scroll function to check if we should query for additional
+     * attachments right away.
+     *
+     * @since 3.5.0
+     *
+     * @returns {void}
+     */
     ready: function() {
-        // Trigger the scroll event to check if we're within the
-        // threshold to query for additional attachments.
         this.scroll();
     },
 
+    /**
+     * Handles scroll events.
+     *
+     * Shows the spinner if we're close to the bottom. Loads more attachments from
+     * server if we're {refreshThreshold} times away from the bottom.
+     *
+     * @since 3.5.0
+     *
+     * @returns {void}
+     */
     scroll: function() {
         var view = this,
@@ -6888 +7022 @@
             toolbar;
 
-        // The scroll event occurs on the document, but the element
-        // that should be checked is the document body.
+        /*
+         * The scroll event occurs on the document, but the element that should be
+         * checked is the document body.
+         */
         if ( el === document ) {
             el = document.body;

trunk/src/wp-includes/js/media/views/attachments.js

@@ -3 +3 @@
     Attachments;
 
-/**
- * wp.media.view.Attachments
- *
- * @memberOf wp.media.view
- *
- * @class
- * @augments wp.media.View
- * @augments wp.Backbone.View
- * @augments Backbone.View
- */
 Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{
     tagName:   'ul',
@@ -21 +11 @@
     },
 
+    /**
+     * Represents the overview of attachments in the Media Library.
+     *
+     * The constructor binds events to the collection this view represents when
+     * adding or removing attachments or resetting the entire collection.
+     *
+     * @since 3.5.0
+     *
+     * @constructs
+     * @memberof wp.media.view
+     *
+     * @augments wp.media.View
+     *
+     * @listens collection:add
+     * @listens collection:remove
+     * @listens collection:reset
+     * @listens controller:library:selection:add
+     * @listens scrollElement:scroll
+     * @listens this:ready
+     * @listens controller:open
+     */
     initialize: function() {
         this.el.id = _.uniqueId('__attachments-view-');
 
+        /**
+         * @param refreshSensitivity The time in milliseconds to throttle the scroll
+         *                           handler.
+         * @param refreshThreshold   The amount of pixels that should be scrolled before
+         *                           loading more attachments from the server.
+         * @param AttachmentView     The view class to be used for models in the
+         *                           collection.
+         * @param sortable           A jQuery sortable options object
+         *                           ( http://api.jqueryui.com/sortable/ ).
+         * @param resize             A boolean indicating whether or not to listen to
+         *                           resize events.
+         * @param idealColumnWidth   The width in pixels which a column should have when
+         *                           calculating the total number of columns.
+         */
         _.defaults( this.options, {
             refreshSensitivity: wp.media.isTouchDevice ? 300 : 200,
@@ -43 +68 @@
         }, this );
 
+        /*
+         * Find the view to be removed, delete it and call the remove function to clear
+         * any set event handlers.
+         */
         this.collection.on( 'remove', function( attachment ) {
             var view = this._viewsByCid[ attachment.cid ];
@@ -70 +99 @@
             this.controller.on( 'open', this.setColumns );
 
-            // Call this.setColumns() after this view has been rendered in the DOM so
-            // attachments get proper width applied.
+            /*
+             * Call this.setColumns() after this view has been rendered in the
+             * DOM so attachments get proper width applied.
+             */
             _.defer( this.setColumns, this );
         }
     },
 
+    /**
+     * Listens to the resizeEvent on the window.
+     *
+     * Adjusts the amount of columns accordingly. First removes any existing event
+     * handlers to prevent duplicate listeners.
+     *
+     * @since 4.0.0
+     *
+     * @listens window:resize
+     *
+     * @returns {void}
+     */
     bindEvents: function() {
         this.$window.off( this.resizeEvent ).on( this.resizeEvent, _.debounce( this.setColumns, 50 ) );
     },
 
+    /**
+     * Focuses the first item in the collection.
+     *
+     * @since 4.0.0
+     *
+     * @returns {void}
+     */
     attachmentFocus: function() {
         this.$( 'li:first' ).focus();
     },
 
+    /**
+     * Restores focus to the selected item in the collection.
+     *
+     * @since 4.0.0
+     *
+     * @returns {void}
+     */
     restoreFocus: function() {
         this.$( 'li.selected:first' ).focus();
     },
 
+    /**
+     * Handles events for arrow key presses.
+     *
+     * Focuses the attachment in the direction of the used arrow key if it exists.
+     *
+     * @since 4.0.0
+     *
+     * @param {KeyboardEvent} event The keyboard event that triggered this function.
+     *
+     * @returns {void}
+     */
     arrowEvent: function( event ) {
         var attachments = this.$el.children( 'li' ),
@@ -98 +166 @@
         }
 
-        // Left arrow
+        // Left arrow = 37.
         if ( 37 === event.keyCode ) {
             if ( 0 === index ) {
@@ -106 +174 @@
         }
 
-        // Up arrow
+        // Up arrow = 38.
         if ( 38 === event.keyCode ) {
             if ( 1 === row ) {
@@ -114 +182 @@
         }
 
-        // Right arrow
+        // Right arrow = 39.
         if ( 39 === event.keyCode ) {
             if ( attachments.length === index ) {
@@ -122 +190 @@
         }
 
-        // Down arrow
+        // Down arrow = 40.
         if ( 40 === event.keyCode ) {
             if ( Math.ceil( attachments.length / perRow ) === row ) {
@@ -131 +199 @@
     },
 
+    /**
+     * Clears any set event handlers.
+     *
+     * @since 3.5.0
+     *
+     * @returns {void}
+     */
     dispose: function() {
         this.collection.props.off( null, null, this );
@@ -137 +212 @@
         }
 
-        /**
-         * call 'dispose' directly on the parent class
-         */
+        // Call 'dispose' directly on the parent class.
         View.prototype.dispose.apply( this, arguments );
     },
 
+    /**
+     * Calculates the amount of columns.
+     *
+     * Calculates the amount of columns and sets it on the data-columns attribute
+     * of .media-frame-content.
+     *
+     * @since 4.0.0
+     *
+     * @returns {void}
+     */
     setColumns: function() {
         var prev = this.columns,
@@ -156 +239 @@
     },
 
+    /**
+     * Initializes jQuery sortable on the attachment list.
+     *
+     * Fails gracefully if jQuery sortable doesn't exist or isn't passed in the
+     * options.
+     *
+     * @since 3.5.0
+     *
+     * @fires collection:reset
+     *
+     * @returns {void}
+     */
     initSortable: function() {
         var collection = this.collection;
@@ -167 +262 @@
             disabled: !! collection.comparator,
 
-            // Change the position of the attachment as soon as the
-            // mouse pointer overlaps a thumbnail.
+            /*
+             * Change the position of the attachment as soon as the mouse pointer overlaps a
+             * thumbnail.
+             */
             tolerance: 'pointer',
 
@@ -176 +273 @@
             },
 
-            // Update the model's index in the collection.
-            // Do so silently, as the view is already accurate.
+            /*
+             * Update the model's index in the collection. Do so silently, as the view
+             * is already accurate.
+             */
             update: function( event, ui ) {
                 var model = collection.at( ui.item.data('sortableIndexStart') ),
@@ -201 +300 @@
                 collection.trigger( 'reset', collection );
 
-                // If the collection is sorted by menu order,
-                // update the menu order.
+                // If the collection is sorted by menu order, update the menu order.
                 collection.saveMenuOrder();
             }
         }, this.options.sortable ) );
 
-        // If the `orderby` property is changed on the `collection`,
-        // check to see if we have a `comparator`. If so, disable sorting.
+        /*
+         * If the `orderby` property is changed on the `collection`, check to see if we
+         * have a `comparator`. If so, disable sorting.
+         */
         collection.props.on( 'change:orderby', function() {
             this.$el.sortable( 'option', 'disabled', !! collection.comparator );
@@ -217 +317 @@
     },
 
+    /**
+     * Disables jQuery sortable if collection has a comparator or collection.orderby
+     * equals menuOrder.
+     *
+     * @since 3.5.0
+     *
+     * @returns {void}
+     */
     refreshSortable: function() {
         if ( ! this.options.sortable || ! $.fn.sortable ) {
@@ -222 +330 @@
         }
 
-        // If the `collection` has a `comparator`, disable sorting.
         var collection = this.collection,
             orderby = collection.props.get('orderby'),
@@ -231 +338 @@
 
     /**
+     * Creates a new view for an attachment and adds it to _viewsByCid.
+     *
+     * @since 3.5.0
+     *
      * @param {wp.media.model.Attachment} attachment
-     * @returns {wp.media.View}
+     *
+     * @returns {wp.media.View} The created view.
      */
     createAttachmentView: function( attachment ) {
@@ -245 +357 @@
     },
 
+    /**
+     * Prepares view for display.
+     *
+     * Creates views for every attachment in collection if the collection is not
+     * empty, otherwise clears all views and loads more attachments.
+     *
+     * @since 3.5.0
+     *
+     * @returns {void}
+     */
     prepare: function() {
-        // Create all of the Attachment views, and replace
-        // the list in a single DOM operation.
         if ( this.collection.length ) {
             this.views.set( this.collection.map( this.createAttachmentView, this ) );
-
-        // If there are no elements, clear the views and load some.
         } else {
             this.views.unset();
@@ -258 +376 @@
     },
 
+    /**
+     * Triggers the scroll function to check if we should query for additional
+     * attachments right away.
+     *
+     * @since 3.5.0
+     *
+     * @returns {void}
+     */
     ready: function() {
-        // Trigger the scroll event to check if we're within the
-        // threshold to query for additional attachments.
         this.scroll();
     },
 
+    /**
+     * Handles scroll events.
+     *
+     * Shows the spinner if we're close to the bottom. Loads more attachments from
+     * server if we're {refreshThreshold} times away from the bottom.
+     *
+     * @since 3.5.0
+     *
+     * @returns {void}
+     */
     scroll: function() {
         var view = this,
@@ -270 +404 @@
             toolbar;
 
-        // The scroll event occurs on the document, but the element
-        // that should be checked is the document body.
+        /*
+         * The scroll event occurs on the document, but the element that should be
+         * checked is the document body.
+         */
         if ( el === document ) {
             el = document.body;