Ticket #43500: gallery-add-documentation.diff

src/wp-includes/js/media/controllers/gallery-add.js

@@ -8 +8 @@
  *
  * A state for selecting more images to add to a gallery.
  *
- * @memberOf wp.media.controller
+ * @since 4.2.0
  *
  * @class
  * @augments wp.media.controller.Library
  * @augments wp.media.controller.State
  * @augments Backbone.Model
  *
- * @param {object}                     [attributes]                         The attributes hash passed to the state.
+ * @memberof wp.media.controller
+ *
+ * @param {Object}                     [attributes]                         The attributes hash passed to the state.
  * @param {string}                     [attributes.id=gallery-library]      Unique identifier.
  * @param {string}                     [attributes.title=Add to Gallery]    Title for the state. Displays in the frame's title region.
  * @param {boolean}                    [attributes.multiple=add]            Whether multi-select is enabled. @todo 'add' doesn't seem do anything special, and gets used as a boolean.
@@ -32 +34 @@
  * @param {boolean}                    [attributes.sortable=true]           Whether the Attachments should be sortable. Depends on the orderby property being set to menuOrder on the attachments collection.
  * @param {boolean}                    [attributes.autoSelect=true]         Whether an uploaded attachment should be automatically added to the selection.
  * @param {boolean}                    [attributes.contentUserSetting=true] Whether the content region's mode should be set and persisted per user.
- * @param {int}                        [attributes.priority=100]            The priority for the state link in the media menu.
+ * @param {number}                     [attributes.priority=100]            The priority for the state link in the media menu.
  * @param {boolean}                    [attributes.syncSelection=false]     Whether the Attachments selection should be persisted from the last state.
  *                                                                          Defaults to false because for this state, because the library of the Edit Gallery state is the selection.
  */
@@ -49 +51 @@
         }, Library.prototype.defaults ),
 
         /**
+         * Initializes the library. Creates a library of images if a library isn't supplied.
+         *
          * @since 3.5.0
+         *
+         * @returns {void}
          */
         initialize: function() {
-                // If a library wasn't supplied, create a library of images.
                 if ( ! this.get('library') ) {
                         this.set( 'library', wp.media.query({ type: 'image' }) );
                 }
@@ -61 +66 @@
         },
 
         /**
+         * Activates the library.
+         *
+         * Removes all event listeners if in edit mode. Creates a validator to check an attachment.
+         * Resets library and re-enables event listeners. Activates edit mode. Calls the parent's activate method.
+         *
          * @since 3.5.0
+         *
+         * @returns {void}
          */
         activate: function() {
                 var library = this.get('library'),
@@ -71 +83 @@
                         library.unobserve( this.editLibrary );
                 }
 
-                // Accepts attachments that exist in the original library and
-                // that do not exist in gallery's library.
+                /*
+                 * Accept attachments that exist in the original library but
+                 * that do not exist in gallery's library yet.
+                 */
                 library.validator = function( attachment ) {
                         return !! this.mirroring.get( attachment.cid ) && ! edit.get( attachment.cid ) && Selection.prototype.validator.apply( this, arguments );
                 };
 
-                // Reset the library to ensure that all attachments are re-added
-                // to the collection. Do so silently, as calling `observe` will
-                // trigger the `reset` event.
+                /*
+                 * Reset the library to ensure that all attachments are re-added
+                 * to the collection. Do so silently, as calling `observe` will
+                 * trigger the `reset` event.
+                 */
                 library.reset( library.mirroring.models, { silent: true });
                 library.observe( edit );
                 this.editLibrary = edit;