Index: /trunk/src/wp-includes/js/customize-preview-widgets.js
===================================================================
--- /trunk/src/wp-includes/js/customize-preview-widgets.js	(revision 42415)
+++ /trunk/src/wp-includes/js/customize-preview-widgets.js	(revision 42416)
@@ -1,5 +1,18 @@
 /* global _wpWidgetCustomizerPreviewSettings */
 
-/** @namespace wp.customize.widgetsPreview */
+/**
+ * Handles the initialization, refreshing and rendering of widget partials and sidebar widgets.
+ *
+ * @since 4.5.0
+ *
+ * @namespace wp.customize.widgetsPreview
+ *
+ * @param {jQuery} $   The jQuery object.
+ * @param {Object} _   The utilities library.
+ * @param {Object} wp  Current WordPress environment instance.
+ * @param {Object} api Information from the API.
+ *
+ * @returns {Object} Widget-related variables.
+ */
 wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function( $, _, wp, api ) {
 
@@ -20,7 +33,11 @@
 
 	/**
-	 * Init widgets preview.
+	 * Initializes the widgets preview.
 	 *
 	 * @since 4.5.0
+	 *
+	 * @memberOf wp.customize.widgetsPreview
+	 *
+	 * @returns {void}
 	 */
 	self.init = function() {
@@ -60,23 +77,21 @@
 	};
 
-	/**
-	 * Partial representing a widget instance.
-	 *
-	 * @memberOf wp.customize.widgetsPreview
-	 * @alias wp.customize.widgetsPreview.WidgetPartial
-	 *
-	 * @class
-	 * @augments wp.customize.selectiveRefresh.Partial
-	 * @since 4.5.0
-	 */
 	self.WidgetPartial = api.selectiveRefresh.Partial.extend(/** @lends wp.customize.widgetsPreview.WidgetPartial.prototype */{
 
 		/**
-		 * Constructor.
-		 *
-		 * @since 4.5.0
-		 * @param {string} id - Partial ID.
-		 * @param {Object} options
-		 * @param {Object} options.params
+		 * Represents a partial widget instance.
+		 *
+		 * @since 4.5.0
+		 *
+		 * @constructs
+		 * @augments wp.customize.selectiveRefresh.Partial
+		 *
+		 * @alias wp.customize.widgetsPreview.WidgetPartial
+		 * @memberOf wp.customize.widgetsPreview
+		 *
+		 * @param {string} id             The partial's ID.
+		 * @param {Object} options        Options used to initialize the partial's
+		 *                                instance.
+		 * @param {Object} options.params The options parameters.
 		 */
 		initialize: function( id, options ) {
@@ -102,7 +117,9 @@
 
 		/**
-		 * Refresh widget partial.
-		 *
-		 * @returns {Promise}
+		 * Refreshes the widget partial.
+		 *
+		 * @since 4.5.0
+		 *
+		 * @returns {Promise|void} Either a promise postponing the refresh, or void.
 		 */
 		refresh: function() {
@@ -119,8 +136,12 @@
 
 		/**
-		 * Send widget-updated message to parent so spinner will get removed from widget control.
-		 *
-		 * @inheritdoc
-		 * @param {wp.customize.selectiveRefresh.Placement} placement
+		 * Sends the widget-updated message to the parent so the spinner will get
+		 * removed from the widget control.
+		 *
+		 * @inheritDoc
+		 * @param {wp.customize.selectiveRefresh.Placement} placement The placement
+		 *                                                            function.
+		 *
+		 * @returns {void}
 		 */
 		renderContent: function( placement ) {
@@ -133,23 +154,20 @@
 	});
 
-	/**
-	 * Partial representing a widget area.
-	 *
-	 * @memberOf wp.customize.widgetsPreview
-	 * @alias wp.customize.widgetsPreview.SidebarPartial
-	 *
-	 * @class
-	 * @augments wp.customize.selectiveRefresh.Partial
-	 * @since 4.5.0
-	 */
 	self.SidebarPartial = api.selectiveRefresh.Partial.extend(/** @lends wp.customize.widgetsPreview.SidebarPartial.prototype */{
 
 		/**
-		 * Constructor.
-		 *
-		 * @since 4.5.0
-		 * @param {string} id - Partial ID.
-		 * @param {Object} options
-		 * @param {Object} options.params
+		 * Represents a partial widget area.
+		 *
+		 * @since 4.5.0
+		 *
+		 * @class
+		 * @augments wp.customize.selectiveRefresh.Partial
+		 *
+		 * @memberOf wp.customize.widgetsPreview
+		 * @alias wp.customize.widgetsPreview.SidebarPartial
+		 *
+		 * @param {string} id             The partial's ID.
+		 * @param {Object} options        Options used to initialize the partial's instance.
+		 * @param {Object} options.params The options parameters.
 		 */
 		initialize: function( id, options ) {
@@ -180,7 +198,9 @@
 
 		/**
-		 * Set up the partial.
-		 *
-		 * @since 4.5.0
+		 * Sets up the partial.
+		 *
+		 * @since 4.5.0
+		 *
+		 * @returns {void}
 		 */
 		ready: function() {
@@ -221,10 +241,14 @@
 
 		/**
-		 * Get the before/after boundary nodes for all instances of this sidebar (usually one).
+		 * Gets the before/after boundary nodes for all instances of this sidebar
+		 * (usually one).
 		 *
 		 * Note that TreeWalker is not implemented in IE8.
 		 *
 		 * @since 4.5.0
+		 *
 		 * @returns {Array.<{before: Comment, after: Comment, instanceNumber: number}>}
+		 *          An array with an object for each sidebar instance, containing the
+		 *          node before and after the sidebar instance and its instance number.
 		 */
 		findDynamicSidebarBoundaryNodes: function() {
@@ -262,8 +286,10 @@
 
 		/**
-		 * Get the placements for this partial.
-		 *
-		 * @since 4.5.0
-		 * @returns {Array}
+		 * Gets the placements for this partial.
+		 *
+		 * @since 4.5.0
+		 *
+		 * @returns {Array} An array containing placement objects for each of the
+		 *                  dynamic sidebar boundary nodes.
 		 */
 		placements: function() {
@@ -287,5 +313,9 @@
 		 * @since 4.5.0
 		 *
-		 * @returns {Array}
+		 * @throws {Error} If there's no settingId.
+		 * @throws {Error} If the setting doesn't exist in the API.
+		 * @throws {Error} If the API doesn't pass an array of widget ids.
+		 *
+		 * @returns {Array} A shallow copy of the array containing widget IDs.
 		 */
 		getWidgetIds: function() {
@@ -306,9 +336,11 @@
 
 		/**
-		 * Reflow widgets in the sidebar, ensuring they have the proper position in the DOM.
-		 *
-		 * @since 4.5.0
-		 *
-		 * @return {Array.<wp.customize.selectiveRefresh.Placement>} List of placements that were reflowed.
+		 * Reflows widgets in the sidebar, ensuring they have the proper position in the
+		 * DOM.
+		 *
+		 * @since 4.5.0
+		 *
+		 * @returns {Array.<wp.customize.selectiveRefresh.Placement>} List of placements
+		 *                                                            that were reflowed.
 		 */
 		reflowWidgets: function() {
@@ -370,10 +402,12 @@
 
 		/**
-		 * Make sure there is a widget instance container in this sidebar for the given widget ID.
-		 *
-		 * @since 4.5.0
-		 *
-		 * @param {string} widgetId
-		 * @returns {wp.customize.selectiveRefresh.Partial} Widget instance partial.
+		 * Makes sure there is a widget instance container in this sidebar for the given
+		 * widget ID.
+		 *
+		 * @since 4.5.0
+		 *
+		 * @param {string} widgetId The widget ID.
+		 *
+		 * @returns {wp.customize.selectiveRefresh.Partial} The widget instance partial.
 		 */
 		ensureWidgetPlacementContainers: function( widgetId ) {
@@ -436,10 +470,12 @@
 
 		/**
-		 * Handle change to the sidebars_widgets[] setting.
-		 *
-		 * @since 4.5.0
-		 *
-		 * @param {Array} newWidgetIds New widget ids.
-		 * @param {Array} oldWidgetIds Old widget ids.
+		 * Handles changes to the sidebars_widgets[] setting.
+		 *
+		 * @since 4.5.0
+		 *
+		 * @param {Array} newWidgetIds New widget IDs.
+		 * @param {Array} oldWidgetIds Old widget IDs.
+		 *
+		 * @returns {void}
 		 */
 		handleSettingChange: function( newWidgetIds, oldWidgetIds ) {
@@ -489,7 +525,12 @@
 
 		/**
-		 * Note that the meat is handled in handleSettingChange because it has the context of which widgets were removed.
-		 *
-		 * @since 4.5.0
+		 * Refreshes the sidebar partial.
+		 *
+		 * Note that the meat is handled in handleSettingChange because it has the
+		 * context of which widgets were removed.
+		 *
+		 * @since 4.5.0
+		 *
+		 * @returns {Promise} A promise postponing the refresh.
 		 */
 		refresh: function() {
@@ -517,7 +558,9 @@
 
 	/**
-	 * Add partials for the registered widget areas (sidebars).
+	 * Adds partials for the registered widget areas (sidebars).
 	 *
 	 * @since 4.5.0
+	 *
+	 * @returns {void}
 	 */
 	self.addPartials = function() {
@@ -537,9 +580,12 @@
 
 	/**
-	 * Calculate the selector for the sidebar's widgets based on the registered sidebar's info.
+	 * Calculates the selector for the sidebar's widgets based on the registered
+	 * sidebar's info.
 	 *
 	 * @memberOf wp.customize.widgetsPreview
 	 *
 	 * @since 3.9.0
+	 *
+	 * @returns {void}
 	 */
 	self.buildWidgetSelectors = function() {
@@ -577,5 +623,5 @@
 
 	/**
-	 * Highlight the widget on widget updates or widget control mouse overs.
+	 * Highlights the widget on widget updates or widget control mouse overs.
 	 *
 	 * @memberOf wp.customize.widgetsPreview
@@ -583,4 +629,6 @@
 	 * @since 3.9.0
 	 * @param  {string} widgetId ID of the widget.
+	 *
+	 * @returns {void}
 	 */
 	self.highlightWidget = function( widgetId ) {
@@ -597,10 +645,12 @@
 
 	/**
-	 * Show a title and highlight widgets on hover. On shift+clicking
-	 * focus the widget control.
+	 * Shows a title and highlights widgets on hover. On shift+clicking focuses the
+	 * widget control.
 	 *
 	 * @memberOf wp.customize.widgetsPreview
 	 *
 	 * @since 3.9.0
+	 *
+	 * @returns {void}
 	 */
 	self.highlightControls = function() {
@@ -614,5 +664,5 @@
 
 		$( selector ).attr( 'title', this.l10n.widgetTooltip );
-
+		// Highlights widget when entering the widget editor.
 		$( document ).on( 'mouseenter', selector, function() {
 			self.preview.send( 'highlight-widget-control', $( this ).prop( 'id' ) );
@@ -631,5 +681,5 @@
 
 	/**
-	 * Parse a widget ID.
+	 * Parses a widget ID.
 	 *
 	 * @memberOf wp.customize.widgetsPreview
@@ -637,6 +687,8 @@
 	 * @since 4.5.0
 	 *
-	 * @param {string} widgetId Widget ID.
-	 * @returns {{idBase: string, number: number|null}}
+	 * @param {string} widgetId The widget ID.
+	 *
+	 * @returns {{idBase: string, number: number|null}} An object containing the
+	 *          idBase and number of the parsed widget ID.
 	 */
 	self.parseWidgetId = function( widgetId ) {
@@ -658,5 +710,5 @@
 
 	/**
-	 * Parse a widget setting ID.
+	 * Parses a widget setting ID.
 	 *
 	 * @memberOf wp.customize.widgetsPreview
@@ -665,5 +717,8 @@
 	 *
 	 * @param {string} settingId Widget setting ID.
-	 * @returns {{idBase: string, number: number|null}|null}
+	 *
+	 * @returns {{idBase: string, number: number|null}|null} Either an object
+	 *          containing the idBase and number of the parsed widget setting ID, or
+	 *          null.
 	 */
 	self.parseWidgetSettingId = function( settingId ) {
@@ -685,5 +740,5 @@
 
 	/**
-	 * Convert a widget ID into a Customizer setting ID.
+	 * Converts a widget ID into a Customizer setting ID.
 	 *
 	 * @memberOf wp.customize.widgetsPreview
@@ -691,6 +746,7 @@
 	 * @since 4.5.0
 	 *
-	 * @param {string} widgetId Widget ID.
-	 * @returns {string} settingId Setting ID.
+	 * @param {string} widgetId The widget ID.
+	 *
+	 * @returns {string} The setting ID.
 	 */
 	self.getWidgetSettingId = function( widgetId ) {
