Improve Customizer JSDoc

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

@@ -12,7 +12,11 @@
  */
 window.wp = window.wp || {};
 
-(function( exports, $ ){
+/**
+ * @param {Object}       wp The WordPress global object.
+ * @param {JQueryStatic} $  The jQuery object.
+ */
+(function( wp, $ ){
 	var api = wp.customize,
 		Loader;
 
@@ -76,6 +80,12 @@ window.wp = window.wp || {};
 			}
 		},
 
+		/**
+		 * Handle popstate event.
+		 *
+		 * @param {JQuery.Event} e The popstate event.
+		 * @return {void}
+		 */
 		popstate: function( e ) {
 			var state = e.originalEvent.state;
 			if ( state && state.customize ) {
@@ -85,6 +95,9 @@ window.wp = window.wp || {};
 			}
 		},
 
+		/**
+		 * Handle hashchange event.
+		 */
 		hashchange: function() {
 			var hash = window.location.toString().split('#')[1];
 
@@ -97,6 +110,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 +124,8 @@ 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.
+		 * @return {string|void} The URL, when navigating to it directly on mobile.
 		 */
 		open: function( src ) {
 
@@ -189,6 +208,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 +294,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

@@ -3,6 +3,11 @@
  */
 
 /* global _wpCustomizeHeader */
+
+/**
+ * @param {JQueryStatic} $  The jQuery object.
+ * @param {Object}       wp The WordPress global object.
+ */
 (function( $, wp ) {
 	var api = wp.customize;
 	/** @namespace wp.customize.HeaderTool */
@@ -21,10 +26,15 @@
 	 * @memberOf wp.customize.HeaderTool
 	 * @alias wp.customize.HeaderTool.ImageModel
 	 *
-	 * @constructor
+	 * @class
 	 * @augments Backbone.Model
 	 */
 	api.HeaderTool.ImageModel = Backbone.Model.extend(/** @lends wp.customize.HeaderTool.ImageModel.prototype */{
+		/**
+		 * Returns the default attributes for a header image.
+		 *
+		 * @return {Object} Default attributes.
+		 */
 		defaults: function() {
 			return {
 				header: {
@@ -39,16 +49,25 @@
 			};
 		},
 
+		/**
+		 * Initializes the model, hiding the header when asked to.
+		 */
 		initialize: function() {
 			this.on('hide', this.hide, this);
 		},
 
+		/**
+		 * Hides the header image, removing it from the site.
+		 */
 		hide: function() {
 			this.set('choice', '');
 			api('header_image').set('remove-header');
 			api('header_image_data').set('remove-header');
 		},
 
+		/**
+		 * Removes the image, hiding the header first if it is the current one.
+		 */
 		destroy: function() {
 			var data = this.get('header'),
 				curr = api.HeaderTool.currentHeader.get('header').attachment_id;
@@ -69,6 +88,9 @@
 			this.trigger('destroy', this, this.collection);
 		},
 
+		/**
+		 * Makes this image the current header image.
+		 */
 		save: function() {
 			if (this.get('random')) {
 				api('header_image').set(this.get('header').random);
@@ -86,6 +108,9 @@
 			api.HeaderTool.combinedList.trigger('control:setImage', this);
 		},
 
+		/**
+		 * Adds the image to the theme's uploaded headers.
+		 */
 		importImage: function() {
 			var data = this.get('header');
 			if (data.attachment_id === undefined) {
@@ -100,6 +125,11 @@
 			} );
 		},
 
+		/**
+		 * Returns whether the image needs cropping for this theme.
+		 *
+		 * @return {boolean} Whether the image should be cropped.
+		 */
 		shouldBeCropped: function() {
 			if (this.get('themeFlexWidth') === true &&
 						this.get('themeFlexHeight') === true) {
@@ -136,17 +166,25 @@
 	 * @memberOf wp.customize.HeaderTool
 	 * @alias wp.customize.HeaderTool.ChoiceList
 	 *
-	 * @constructor
+	 * @class
 	 * @augments Backbone.Collection
 	 */
 	api.HeaderTool.ChoiceList = Backbone.Collection.extend({
 		model: api.HeaderTool.ImageModel,
 
-		// Ordered from most recently used to least.
+		/**
+		 * Orders the collection from most recently used to least.
+		 *
+		 * @param {Backbone.Model} model The model to sort.
+		 * @return {number} The sort order.
+		 */
 		comparator: function(model) {
 			return -model.get('header').timestamp;
 		},
 
+		/**
+		 * Initializes the collection from the uploaded header images.
+		 */
 		initialize: function() {
 			var current = api.HeaderTool.currentHeader.get('choice').replace(/^https?:\/\//, ''),
 				isRandom = this.isRandomChoice(api.get().header_image);
@@ -192,6 +230,11 @@
 			}
 		},
 
+		/**
+		 * Removes an image's previous crop once it has been replaced.
+		 *
+		 * @param {Backbone.Model} model Model.
+		 */
 		maybeRemoveOldCrop: function( model ) {
 			var newID = model.get( 'header' ).attachment_id || false,
 			 	oldCrop;
@@ -211,12 +254,20 @@
 			}
 		},
 
+		/**
+		 * Adds the random choice once a single image is left.
+		 */
 		maybeAddRandomChoice: function() {
 			if (this.size() === 1) {
 				this.addRandomChoice();
 			}
 		},
 
+		/**
+		 * Adds the random image choice to the collection.
+		 *
+		 * @param {string} initialChoice Initial choice.
+		 */
 		addRandomChoice: function(initialChoice) {
 			var isRandomSameType = RegExp(this.type).test(initialChoice),
 				randomChoice = 'random-' + this.type + '-image';
@@ -234,14 +285,30 @@
 			});
 		},
 
+		/**
+		 * Returns whether a choice is one of the random image choices.
+		 *
+		 * @param {string} choice Choice.
+		 * @return {boolean} Whether the choice is random.
+		 */
 		isRandomChoice: function(choice) {
 			return (/^random-(uploaded|default)-image$/).test(choice);
 		},
 
+		/**
+		 * Returns whether the list title should be hidden.
+		 *
+		 * @return {boolean} Whether the title should be hidden.
+		 */
 		shouldHideTitle: function() {
 			return this.size() < 2;
 		},
 
+		/**
+		 * Marks a single image as the selected one.
+		 *
+		 * @param {Backbone.Model} model Model.
+		 */
 		setImage: function(model) {
 			this.each(function(m) {
 				m.set('selected', false);
@@ -252,6 +319,9 @@
 			}
 		},
 
+		/**
+		 * Clears the selection.
+		 */
 		removeImage: function() {
 			this.each(function(m) {
 				m.set('selected', false);
@@ -266,11 +336,14 @@
 	 * @memberOf wp.customize.HeaderTool
 	 * @alias wp.customize.HeaderTool.DefaultsList
 	 *
-	 * @constructor
+	 * @class
 	 * @augments wp.customize.HeaderTool.ChoiceList
 	 * @augments Backbone.Collection
 	 */
 	api.HeaderTool.DefaultsList = api.HeaderTool.ChoiceList.extend({
+		/**
+		 * Initializes the collection from the theme's default header images.
+		 */
 		initialize: function() {
 			this.type = 'default';
 			this.data = _wpCustomizeHeader.defaults;