Improve Customizer JSDoc

src/js/_enqueues/wp/customize/base.js

@@ -17,10 +17,10 @@ window.wp = window.wp || {};
 	 * Similar to `goog.inherits`, but uses a hash of prototype properties and
 	 * class properties to be extended.
 	 *
-	 * @param object parent      Parent class constructor to inherit from.
-	 * @param object protoProps  Properties to apply to the prototype for use as class instance properties.
-	 * @param object staticProps Properties to apply directly to the class constructor.
-	 * @return child The subclassed constructor.
+	 * @param {object} parent      Parent class constructor to inherit from.
+	 * @param {object} protoProps  Properties to apply to the prototype for use as class instance properties.
+	 * @param {object} staticProps Properties to apply directly to the class constructor.
+	 * @return {function} The subclassed constructor.
 	 */
 	inherits = function( parent, protoProps, staticProps ) {
 		var child;
@@ -108,9 +108,9 @@ window.wp = window.wp || {};
 	/**
 	 * Creates a subclass of the class.
 	 *
-	 * @param object protoProps  Properties to apply to the prototype.
-	 * @param object staticProps Properties to apply directly to the class.
-	 * @return child The subclass.
+	 * @param {object} protoProps Properties to apply to the prototype.
+	 * @param {object} staticProps Properties to apply directly to the class.
+	 * @return {function} The subclass.
 	 */
 	api.Class.extend = function( protoProps, staticProps ) {
 		var child = inherits( this, protoProps, staticProps );
@@ -372,7 +372,7 @@ window.wp = window.wp || {};
 		 * Get the instance of an item.
 		 *
 		 * @param {string} id The ID of the item.
-		 * @return {[type]} [description]
+		 * @return {mixed} The item instance.
 		 */
 		value: function( id ) {
 			return this._value[ id ];
@@ -494,7 +494,7 @@ window.wp = window.wp || {};
 		 * For example:
 		 *     when( id1, id2, id3, function( value1, value2, value3 ) {} );
 		 *
-		 * @return $.Deferred.promise();
+		 * @return {jQuery.Promise} Promise.
 		 */
 		when: function() {
 			var self = this,
@@ -555,9 +555,9 @@ window.wp = window.wp || {};
 
 
 	/**
-	 * Cast a string to a jQuery collection if it isn't already.
+	 * Cast a string to a jQuery object if it isn't already.
 	 *
-	 * @param {string|jQuery collection} element
+	 * @param {string|jQuery} element
 	 */
 	api.ensure = function( element ) {
 		return typeof element === 'string' ? $( element ) : element;
@@ -683,11 +683,11 @@ window.wp = window.wp || {};
 		/**
 		 * Initialize Messenger.
 		 *
-		 * @param {Object} params  - Parameters to configure the messenger.
-		 *        {string} params.url          - The URL to communicate with.
-		 *        {window} params.targetWindow - The window instance to communicate with. Default window.parent.
-		 *        {string} params.channel      - If provided, will send the channel with each message and only accept messages a matching channel.
-		 * @param {Object} options - Extend any instance parameter or method with this object.
+		 * @param {Object} params               - Parameters to configure the messenger.
+		 * @param {string} params.url           - The URL to communicate with.
+		 * @param {window} params.targetWindow  - The window instance to communicate with. Default window.parent.
+		 * @param {string} [params.channel]     - If provided, will send the channel with each message and only accept messages a matching channel.
+		 * @param {Object} options              - Extend any instance parameter or method with this object.
 		 */
 		initialize: function( params, options ) {
 			// Target the parent frame by default, but only if a parent frame exists.

src/js/_enqueues/wp/customize/loader.js

@@ -76,6 +76,9 @@ window.wp = window.wp || {};
 			}
 		},
 
+		/**
+		 * Handle popstate event.
+		 */
 		popstate: function( e ) {
 			var state = e.originalEvent.state;
 			if ( state && state.customize ) {
@@ -85,6 +88,9 @@ window.wp = window.wp || {};
 			}
 		},
 
+		/**
+		 * Handle hashchange event.
+		 */
 		hashchange: function() {
 			var hash = window.location.toString().split('#')[1];
 
@@ -97,6 +103,11 @@ window.wp = window.wp || {};
 			}
 		},
 
+		/**
+		 * Handle beforeunload event.
+		 *
+		 * @return {string|void} Confirmation message if there are unsaved changes.
+		 */
 		beforeunload: function () {
 			if ( ! Loader.saved() ) {
 				return Loader.settings.l10n.saveAlert;
@@ -106,7 +117,7 @@ window.wp = window.wp || {};
 		/**
 		 * Open the Customizer overlay for a specific URL.
 		 *
-		 * @param string src URL to load in the Customizer.
+		 * @param {string} src URL to load in the Customizer.
 		 */
 		open: function( src ) {
 
@@ -189,6 +200,11 @@ window.wp = window.wp || {};
 			this.trigger( 'open' );
 		},
 
+		/**
+		 * Push the state of the Customizer onto the history stack.
+		 *
+		 * @param {string} src URL to push.
+		 */
 		pushState: function ( src ) {
 			var hash = src.split( '?' )[1];
 
@@ -270,10 +286,16 @@ window.wp = window.wp || {};
 		 * Overlay hide/show utility methods.
 		 */
 		overlay: {
+			/**
+			 * Show the overlay.
+			 */
 			show: function() {
 				this.element.fadeIn( 200, Loader.opened );
 			},
 
+			/**
+			 * Hide the overlay.
+			 */
 			hide: function() {
 				this.element.fadeOut( 200, Loader.closed );
 			}

src/js/_enqueues/wp/customize/models.js

@@ -25,6 +25,11 @@
 	 * @augments Backbone.Model
 	 */
 	api.HeaderTool.ImageModel = Backbone.Model.extend(/** @lends wp.customize.HeaderTool.ImageModel.prototype */{
+		/**
+		 * Default attributes.
+		 *
+		 * @return {Object} Default attributes.
+		 */
 		defaults: function() {
 			return {
 				header: {
@@ -39,16 +44,25 @@
 			};
 		},
 
+		/**
+		 * Initialize.
+		 */
 		initialize: function() {
 			this.on('hide', this.hide, this);
 		},
 
+		/**
+		 * Hide.
+		 */
 		hide: function() {
 			this.set('choice', '');
 			api('header_image').set('remove-header');
 			api('header_image_data').set('remove-header');
 		},
 
+		/**
+		 * Destroy.
+		 */
 		destroy: function() {
 			var data = this.get('header'),
 				curr = api.HeaderTool.currentHeader.get('header').attachment_id;
@@ -69,6 +83,9 @@
 			this.trigger('destroy', this, this.collection);
 		},
 
+		/**
+		 * Save.
+		 */
 		save: function() {
 			if (this.get('random')) {
 				api('header_image').set(this.get('header').random);
@@ -86,6 +103,9 @@
 			api.HeaderTool.combinedList.trigger('control:setImage', this);
 		},
 
+		/**
+		 * Import image.
+		 */
 		importImage: function() {
 			var data = this.get('header');
 			if (data.attachment_id === undefined) {
@@ -100,6 +120,11 @@
 			} );
 		},
 
+		/**
+		 * Should be cropped.
+		 *
+		 * @return {boolean} Whether the image should be cropped.
+		 */
 		shouldBeCropped: function() {
 			if (this.get('themeFlexWidth') === true &&
 						this.get('themeFlexHeight') === true) {
@@ -142,11 +167,19 @@
 	api.HeaderTool.ChoiceList = Backbone.Collection.extend({
 		model: api.HeaderTool.ImageModel,
 
-		// Ordered from most recently used to least.
+		/**
+		 * Comparator.
+		 *
+		 * @param {Backbone.Model} model Model.
+		 * @return {number} Order.
+		 */
 		comparator: function(model) {
 			return -model.get('header').timestamp;
 		},
 
+		/**
+		 * Initialize.
+		 */
 		initialize: function() {
 			var current = api.HeaderTool.currentHeader.get('choice').replace(/^https?:\/\//, ''),
 				isRandom = this.isRandomChoice(api.get().header_image);
@@ -192,6 +225,11 @@
 			}
 		},
 
+		/**
+		 * Maybe remove old crop.
+		 *
+		 * @param {Backbone.Model} model Model.
+		 */
 		maybeRemoveOldCrop: function( model ) {
 			var newID = model.get( 'header' ).attachment_id || false,
 			 	oldCrop;
@@ -211,12 +249,20 @@
 			}
 		},
 
+		/**
+		 * Maybe add random choice.
+		 */
 		maybeAddRandomChoice: function() {
 			if (this.size() === 1) {
 				this.addRandomChoice();
 			}
 		},
 
+		/**
+		 * Add random choice.
+		 *
+		 * @param {string} initialChoice Initial choice.
+		 */
 		addRandomChoice: function(initialChoice) {
 			var isRandomSameType = RegExp(this.type).test(initialChoice),
 				randomChoice = 'random-' + this.type + '-image';
@@ -234,14 +280,30 @@
 			});
 		},
 
+		/**
+		 * Is random choice?
+		 *
+		 * @param {string} choice Choice.
+		 * @return {boolean} Whether the choice is random.
+		 */
 		isRandomChoice: function(choice) {
 			return (/^random-(uploaded|default)-image$/).test(choice);
 		},
 
+		/**
+		 * Should hide title?
+		 *
+		 * @return {boolean} Whether the title should be hidden.
+		 */
 		shouldHideTitle: function() {
 			return this.size() < 2;
 		},
 
+		/**
+		 * Set image.
+		 *
+		 * @param {Backbone.Model} model Model.
+		 */
 		setImage: function(model) {
 			this.each(function(m) {
 				m.set('selected', false);
@@ -252,6 +314,9 @@
 			}
 		},
 
+		/**
+		 * Remove image.
+		 */
 		removeImage: function() {
 			this.each(function(m) {
 				m.set('selected', false);
@@ -271,6 +336,9 @@
 	 * @augments Backbone.Collection
 	 */
 	api.HeaderTool.DefaultsList = api.HeaderTool.ChoiceList.extend({
+		/**
+		 * Initialize.
+		 */
 		initialize: function() {
 			this.type = 'default';
 			this.data = _wpCustomizeHeader.defaults;

src/js/_enqueues/wp/customize/nav-menus.js

@@ -2103,7 +2103,7 @@
 		 **********************************************************************/
 
 		/**
-		 * @return {wp.customize.controlConstructor.nav_menu|null}
+		 * @return {wp.customize.Control|null}
 		 */
 		getMenuControl: function() {
 			var control = this, settingValue = control.setting();
@@ -3019,7 +3019,7 @@
 		},
 
 		/**
-		 * @return {wp.customize.controlConstructor.nav_menu_item[]}
+		 * @return {wp.customize.Control[]}
 		 */
 		getMenuItemControls: function() {
 			var menuControl = this,
@@ -3124,7 +3124,7 @@
 		 * Add a new item to this menu.
 		 *
 		 * @param {Object} item - Value for the nav_menu_item setting to be created.
-		 * @return {wp.customize.Menus.controlConstructor.nav_menu_item} The newly-created nav_menu_item control instance.
+		 * @return {wp.customize.Control} The newly-created nav_menu_item control instance.
 		 */
 		addItemToMenu: function( item ) {
 			var menuControl = this, customizeId, settingArgs, setting, menuItemControl, placeholderId, position = 0, priority = 10,
@@ -3189,7 +3189,7 @@
 		 *
 		 * @since 4.9.0
 		 *
-		 * @param {wp.customize.controlConstructor.nav_menu_item[]} optionalMenuItemControls
+		 * @param {wp.customize.Control[]} optionalMenuItemControls
 		 */
 		updateInvitationVisibility: function ( optionalMenuItemControls ) {
 			var menuItemControls = optionalMenuItemControls || this.getMenuItemControls();
@@ -3509,8 +3509,8 @@
 	 *
 	 * @alias wp.customize.Menus.getMenuControl
 	 *
-	 * @param menuId
-	 * @return {wp.customize.controlConstructor.menus[]}
+	 * @param {string|number} menuId The menu ID.
+	 * @return {wp.customize.Control} The menu control.
 	 */
 	api.Menus.getMenuControl = function( menuId ) {
 		return api.control( 'nav_menu[' + menuId + ']' );