Add some docs to Customizer JS.

Props ericlewis.
See #29157.

Built from https://develop.svn.wordpress.org/trunk@29451


git-svn-id: http://core.svn.wordpress.org/trunk@29229 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-admin/js/customize-controls.js

@@ -3,6 +3,10 @@
 	var api = wp.customize;
 
 	/**
+	 * @constructor
+	 * @augments wp.customize.Value
+	 * @augments wp.customize.Class
+	 *
 	 * @param options
 	 * - previewer - The Previewer instance to sync with.
 	 * - transport - The transport to use for previewing. Supports 'refresh' and 'postMessage'.
@@ -26,6 +30,10 @@
 		}
 	});
 
+	/**
+	 * @constructor
+	 * @augments wp.customize.Class
+	 */
 	api.Control = api.Class.extend({
 		initialize: function( id, options ) {
 			var control = this,
@@ -87,6 +95,9 @@
 			control.toggle( control.active() );
 		},
 
+		/**
+		 * @abstract
+		 */
 		ready: function() {},
 
 		/**
@@ -141,6 +152,11 @@
 		}
 	});
 
+	/**
+	 * @constructor
+	 * @augments wp.customize.Control
+	 * @augments wp.customize.Class
+	 */
 	api.ColorControl = api.Control.extend({
 		ready: function() {
 			var control = this,
@@ -157,6 +173,11 @@
 		}
 	});
 
+	/**
+	 * @constructor
+	 * @augments wp.customize.Control
+	 * @augments wp.customize.Class
+	 */
 	api.UploadControl = api.Control.extend({
 		ready: function() {
 			var control = this;
@@ -210,6 +231,12 @@
 		}
 	});
 
+	/**
+	 * @constructor
+	 * @augments wp.customize.UploadControl
+	 * @augments wp.customize.Control
+	 * @augments wp.customize.Class
+	 */
 	api.ImageControl = api.UploadControl.extend({
 		ready: function() {
 			var control = this,
@@ -328,6 +355,11 @@
 		}
 	});
 
+	/**
+	 * @constructor
+	 * @augments wp.customize.Control
+	 * @augments wp.customize.Class
+	 */
 	api.HeaderControl = api.Control.extend({
 		ready: function() {
 			this.btnRemove        = $('#customize-control-header_image .actions .remove');
@@ -544,6 +576,12 @@
 	// Create the collection of Control objects.
 	api.control = new api.Values({ defaultConstructor: api.Control });
 
+	/**
+	 * @constructor
+	 * @augments wp.customize.Messenger
+	 * @augments wp.customize.Class
+	 * @mixes wp.customize.Events
+	 */
 	api.PreviewFrame = api.Messenger.extend({
 		sensitivity: 2000,
 
@@ -714,11 +752,22 @@
 
 	(function(){
 		var uuid = 0;
+		/**
+		 * Create a universally unique identifier.
+		 *
+		 * @return {int}
+		 */
 		api.PreviewFrame.uuid = function() {
 			return 'preview-' + uuid++;
 		};
 	}());
 
+	/**
+	 * @constructor
+	 * @augments wp.customize.Messenger
+	 * @augments wp.customize.Class
+	 * @mixes wp.customize.Events
+	 */
 	api.Previewer = api.Messenger.extend({
 		refreshBuffer: 250,
 
@@ -924,10 +973,6 @@
 		}
 	});
 
-	/* =====================================================================
-	 * Ready.
-	 * ===================================================================== */
-
 	api.controlConstructor = {
 		color:  api.ColorControl,
 		upload: api.UploadControl,

wp-includes/class-wp-customize-manager.php

@@ -16,7 +16,7 @@
  */
 final class WP_Customize_Manager {
 	/**
-	 * An instance of the theme that is being customized.
+	 * An instance of the theme being previewed.
 	 *
 	 * @var WP_Theme
 	 */
@@ -30,8 +30,7 @@ final class WP_Customize_Manager {
 	protected $original_stylesheet;
 
 	/**
-	 * Whether filters have been set to change the active theme to the theme being
-	 * customized.
+	 * Whether this is a Customizer pageload.
 	 *
 	 * @var boolean
 	 */
@@ -183,7 +182,6 @@ final class WP_Customize_Manager {
 				$this->wp_die( -1 );
 		}
 
-		// All good, let's do some internal business to preview the theme.
 		$this->start_previewing_theme();
 	}
 
@@ -200,7 +198,8 @@ final class WP_Customize_Manager {
 	}
 
 	/**
-	 * Start previewing the selected theme by adding filters to change the current theme.
+	 * If the theme to be previewed isn't the active theme, add filter callbacks
+	 * to swap it out at runtime.
 	 *
 	 * @since 3.4.0
 	 */

wp-includes/js/customize-preview.js

@@ -2,6 +2,11 @@
 	var api = wp.customize,
 		debounce;
 
+	/**
+	 * Returns a debounced version of the function.
+	 *
+	 * @todo Require Underscore.js for this file and retire this.
+	 */
 	debounce = function( fn, delay, context ) {
 		var timeout;
 		return function() {
@@ -17,6 +22,12 @@
 		};
 	};
 
+	/**
+	 * @constructor
+	 * @augments wp.customize.Messenger
+	 * @augments wp.customize.Class
+	 * @mixes wp.customize.Events
+	 */
 	api.Preview = api.Messenger.extend({
 		/**
 		 * Requires params: