Add some docs to Customizer JS.

Props ericlewis.
See #29157.

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


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

wp-includes/js/customize-base.js

@@ -1,25 +1,22 @@
 window.wp = window.wp || {};
 
 (function( exports, $ ){
-	var api, extend, ctor, inherits,
+	var api = {}, ctor, inherits,
 		slice = Array.prototype.slice;
 
-	/* =====================================================================
-	 * Micro-inheritance - thank you, backbone.js.
-	 * ===================================================================== */
-
-	extend = function( protoProps, classProps ) {
-		var child = inherits( this, protoProps, classProps );
-		child.extend = this.extend;
-		return child;
-	};
-
 	// Shared empty constructor function to aid in prototype-chain creation.
 	ctor = function() {};
 
-	// Helper function to correctly set up the prototype chain, for subclasses.
+	/**
-	// Similar to `goog.inherits`, but uses a hash of prototype properties and
+	 * Helper function to correctly set up the prototype chain, for subclasses.
-	// class properties to be extended.
+	 * 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.
+	 */
 	inherits = function( parent, protoProps, staticProps ) {
 		var child;
 
@@ -65,12 +62,9 @@ window.wp = window.wp || {};
 		return child;
 	};
 
-	api = {};
+	/**
-
+	 * Base class for object inheritance.
-	/* =====================================================================
+	 */
-	 * Base class.
-	 * ===================================================================== */
-
 	api.Class = function( applicator, argsArray, options ) {
 		var magic, args = arguments;
 
@@ -92,6 +86,19 @@ window.wp = window.wp || {};
 		return magic;
 	};
 
+	/**
+	 * 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.
+	 */
+	api.Class.extend = function( protoProps, classProps ) {
+		var child = inherits( this, protoProps, classProps );
+		child.extend = this.extend;
+		return child;
+	};
+
 	api.Class.applicator = {};
 
 	api.Class.prototype.initialize = function() {};
@@ -116,12 +123,11 @@ window.wp = window.wp || {};
 		return false;
 	};
 
-	api.Class.extend = extend;
+	/**
-
+	 * An events manager object, offering the ability to bind to and trigger events.
-	/* =====================================================================
+	 *
-	 * Events mixin.
+	 * Used as a mixin.
-	 * ===================================================================== */
+	 */
-
 	api.Events = {
 		trigger: function( id ) {
 			if ( this.topics && this.topics[ id ] )
@@ -143,10 +149,11 @@ window.wp = window.wp || {};
 		}
 	};
 
-	/* =====================================================================
+	/**
 	 * Observable values that support two-way binding.
-	 * ===================================================================== */
+	 *
-
+	 * @constuctor
+	 */
 	api.Value = api.Class.extend({
 		initialize: function( initial, options ) {
 			this._value = initial; // @todo: potentially change this to a this.set() call.
@@ -254,10 +261,13 @@ window.wp = window.wp || {};
 		}
 	});
 
-	/* =====================================================================
+	/**
 	 * A collection of observable values.
-	 * ===================================================================== */
+	 *
-
+	 * @constuctor
+	 * @augments wp.customize.Class
+	 * @mixes wp.customize.Events
+	 */
 	api.Values = api.Class.extend({
 		defaultConstructor: api.Value,
 
@@ -379,16 +389,25 @@ window.wp = window.wp || {};
 
 	$.extend( api.Values.prototype, api.Events );
 
-	/* =====================================================================
-	 * An observable value that syncs with an element.
-	 *
-	 * Handles inputs, selects, and textareas by default.
-	 * ===================================================================== */
 
+	/**
+	 * Cast a string to a jQuery collection if it isn't already.
+	 *
+	 * @param {string|jQuery collection} element
+	 */
 	api.ensure = function( element ) {
 		return typeof element == 'string' ? $( element ) : element;
 	};
 
+	/**
+	 * An observable value that syncs with an element.
+	 *
+	 * Handles inputs, selects, and textareas by default.
+	 *
+	 * @constuctor
+	 * @augments wp.customize.Value
+	 * @augments wp.customize.Class
+	 */
 	api.Element = api.Value.extend({
 		initialize: function( element, options ) {
 			var self = this,
@@ -442,7 +461,7 @@ window.wp = window.wp || {};
 
 	api.Element.synchronizer = {};
 
-	$.each( [ 'html', 'val' ], function( i, method ) {
+	$.each( [ 'html', 'val' ], function( index, method ) {
 		api.Element.synchronizer[ method ] = {
 			update: function( to ) {
 				this.element[ method ]( to );
@@ -473,13 +492,24 @@ window.wp = window.wp || {};
 		}
 	};
 
-	/* =====================================================================
-	 * Messenger for postMessage.
-	 * ===================================================================== */
-
 	$.support.postMessage = !! window.postMessage;
 
+	/**
+	 * Messenger for postMessage.
+	 *
+	 * @constuctor
+	 * @augments wp.customize.Class
+	 * @mixes wp.customize.Events
+	 */
 	api.Messenger = api.Class.extend({
+		/**
+		 * Create a new Value.
+		 *
+		 * @param  {string} key     Unique identifier.
+		 * @param  {mixed}  initial Initial value.
+		 * @param  {mixed}  options Options hash. Optional.
+		 * @return {Value}          Class instance of the Value.
+		 */
 		add: function( key, initial, options ) {
 			return this[ key ] = new api.Value( initial, options );
 		},
@@ -570,10 +600,7 @@ window.wp = window.wp || {};
 	// Add the Events mixin to api.Messenger.
 	$.extend( api.Messenger.prototype, api.Events );
 
-	/* =====================================================================
+	// Core customize object.
-	 * Core customize object.
-	 * ===================================================================== */
-
 	api = $.extend( new api.Values(), api );
 	api.get = function() {
 		var result = {};
@@ -585,6 +612,6 @@ window.wp = window.wp || {};
 		return result;
 	};
 
-	// Expose the API to the world.
+	// Expose the API publicly on window.wp.customize
 	exports.customize = api;
 })( wp, jQuery );

wp-includes/js/customize-loader.js

@@ -10,7 +10,20 @@ window.wp = window.wp || {};
 		hashchange: ('onhashchange' in window) && (document.documentMode === undefined || document.documentMode > 7)
 	});
 
+	/**
+	 * Allows the Customizer to be overlayed on any page.
+	 *
+	 * By default, any element in the body with the load-customize class will open
+	 * the Customizer overlay with the URL specified.
+	 *
+	 *     e.g. <a class="load-customize" href="http://siteurl.com/2014/01/02/post">Open customizer</a>
+	 *
+	 * @augments wp.customize.Events
+	 */
 	Loader = $.extend( {}, api.Events, {
+		/**
+		 * Setup the Loader; triggered on document#ready.
+		 */
 		initialize: function() {
 			this.body = $( document.body );
 
@@ -23,9 +36,12 @@ window.wp = window.wp || {};
 			this.window  = $( window );
 			this.element = $( '<div id="customize-container" />' ).appendTo( this.body );
 
+			// Bind events for opening and closing the overlay.
 			this.bind( 'open', this.overlay.show );
 			this.bind( 'close', this.overlay.hide );
 
+			// Any element in the body with the `load-customize` class opens
+			// the Customizer.
 			$('#wpbody').on( 'click', '.load-customize', function( event ) {
 				event.preventDefault();
 
@@ -73,6 +89,11 @@ window.wp = window.wp || {};
 			}
 		},
 
+		/**
+		 * Open the customizer overlay for a specific URL.
+		 *
+		 * @param  string src URL to load in the Customizer.
+		 */
 		open: function( src ) {
 
 			if ( this.active ) {
@@ -148,10 +169,16 @@ window.wp = window.wp || {};
 			}
 		},
 
+		/**
+		 * Callback after the customizer has been opened.
+		 */
 		opened: function() {
 			Loader.body.addClass( 'customize-active full-overlay-active' );
 		},
 
+		/**
+		 * Close the Customizer overlay and return focus to the link that opened it.
+		 */
 		close: function() {
 			if ( ! this.active ) {
 				return;
@@ -174,6 +201,9 @@ window.wp = window.wp || {};
 			}
 		},
 
+		/**
+		 * Callback after the customizer has been closed.
+		 */
 		closed: function() {
 			Loader.iframe.remove();
 			Loader.messenger.destroy();
@@ -184,10 +214,16 @@ window.wp = window.wp || {};
 			$( window ).off( 'beforeunload', Loader.beforeunload );
 		},
 
+		/**
+		 * Callback for the `load` event on the Customizer iframe.
+		 */
 		loaded: function() {
 			Loader.body.removeClass('customize-loading');
 		},
 
+		/**
+		 * Overlay hide/show utility methods.
+		 */
 		overlay: {
 			show: function() {
 				this.element.fadeIn( 200, Loader.opened );
@@ -199,11 +235,12 @@ window.wp = window.wp || {};
 		}
 	});
 
+	// Bootstrap the Loader on document#ready.
 	$( function() {
 		Loader.settings = _wpCustomizeLoaderSettings;
 		Loader.initialize();
 	});
 
-	// Expose the API to the world.
+	// Expose the API publicly on window.wp.customize.Loader
 	api.Loader = Loader;
 })( wp, jQuery );