From af851b9bdaf8ab30958bd33b6468e22372e8af83 Mon Sep 17 00:00:00 2001
From: Scott Taylor <wonderboymusic@git.wordpress.org>
Date: Fri, 8 Aug 2014 23:30:30 +0000
Subject: [PATCH] Add some docs to Customizer JS.

Props ericlewis.
See #29157.


git-svn-id: https://develop.svn.wordpress.org/trunk@29451 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-admin/js/customize-controls.js         | 53 +++++++++++++++++--
 .../class-wp-customize-manager.php            |  9 ++--
 src/wp-includes/js/customize-preview.js       | 11 ++++
 3 files changed, 64 insertions(+), 9 deletions(-)

diff --git a/src/wp-admin/js/customize-controls.js b/src/wp-admin/js/customize-controls.js
index 5ea7aff73c..85b171dbe9 100644
--- a/src/wp-admin/js/customize-controls.js
+++ b/src/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,
diff --git a/src/wp-includes/class-wp-customize-manager.php b/src/wp-includes/class-wp-customize-manager.php
index 5e2ba5dd89..5067126186 100644
--- a/src/wp-includes/class-wp-customize-manager.php
+++ b/src/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
 	 */
diff --git a/src/wp-includes/js/customize-preview.js b/src/wp-includes/js/customize-preview.js
index 99643fb1c2..6da26f47a0 100644
--- a/src/wp-includes/js/customize-preview.js
+++ b/src/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: