Customize: Clean up docs and code style for customize changes in 4.7.

* Adds missing `resolve`/`fail` for promise returned by `loadThemePreview`.
* Adds missing jsdoc blocks and tags.
* Adds missing phpdoc and makes corrections.

See #37770.
Fixes #38908.

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


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

wp-admin/js/customize-controls.js

@@ -45,6 +45,9 @@
 		 * previewer.send() call to then fallback to refresh will not work.
 		 *
 		 * @since 3.4.0
+		 * @access public
+		 *
+		 * @returns {void}
 		 */
 		preview: function() {
 			var setting = this, transport;
@@ -55,9 +58,9 @@
 			}
 
 			if ( 'postMessage' === transport ) {
-				return setting.previewer.send( 'setting', [ setting.id, setting() ] );
+				setting.previewer.send( 'setting', [ setting.id, setting() ] );
 			} else if ( 'refresh' === transport ) {
-				return setting.previewer.refresh();
+				setting.previewer.refresh();
 			}
 		},
 
@@ -130,6 +133,9 @@
 	/**
 	 * Get the dirty setting values.
 	 *
+	 * @since 4.7.0
+	 * @access public
+	 *
 	 * @param {object} [options] Options.
 	 * @param {boolean} [options.unsaved=false] Whether only values not saved yet into a changeset will be returned (differential changes).
 	 * @returns {object} Dirty setting values.
@@ -158,9 +164,12 @@
 	/**
 	 * Request updates to the changeset.
 	 *
+	 * @since 4.7.0
+	 * @access public
+	 *
 	 * @param {object} [changes] Mapping of setting IDs to setting params each normally including a value property, or mapping to null.
 	 *                           If not provided, then the changes will still be obtained from unsaved dirty settings.
-	 * @returns {jQuery.Promise}
+	 * @returns {jQuery.Promise} Promise resolving with the response data.
 	 */
 	api.requestChangesetUpdate = function requestChangesetUpdate( changes ) {
 		var deferred, request, submittedChanges = {}, data;
@@ -684,10 +693,10 @@
 		 * Animate container state change if transitions are supported by the browser.
 		 *
 		 * @since 4.7.0
+		 * @private
 		 *
 		 * @param {function} completeCallback Function to be called after transition is completed.
 		 * @returns {void}
-		 * @private
 		 */
 		_animateChangeExpanded: function( completeCallback ) {
 			// Return if CSS transitions are not supported.
@@ -778,6 +787,7 @@
 		 * method to handle animating the panel/section into and out of view.
 		 *
 		 * @since 4.7.0
+		 * @access public
 		 *
 		 * @returns {jQuery} Detached content element.
 		 */
@@ -935,7 +945,7 @@
 				content.toggleClass( 'open' );
 				content.slideToggle();
 				content.attr( 'aria-expanded', function ( i, attr ) {
-					return attr === 'true' ? 'false' : 'true';
+					return 'true' === attr ? 'false' : 'true';
 				});
 			});
 		},
@@ -1419,6 +1429,7 @@
 		 * Load theme preview.
 		 *
 		 * @since 4.7.0
+		 * @access public
 		 *
 		 * @param {string} themeId Theme ID.
 		 * @returns {jQuery.promise} Promise.
@@ -1451,9 +1462,11 @@
 				request.done( function() {
 					$( window ).off( 'beforeunload.customize-confirm' );
 					top.location.href = urlParser.href;
+					deferred.resolve();
 				} );
 				request.fail( function() {
 					overlay.removeClass( 'customize-loading' );
+					deferred.reject();
 				} );
 			};
 
@@ -2273,8 +2286,8 @@
 				// Reset the create page form.
 				container.slideUp( 180 );
 				toggle.slideDown( 180 );
-			} )
+			} );
-			.always( function() {
+			promise.always( function() {
 				input.val( '' ).removeAttr( 'disabled' );
 			} );
 		}
@@ -2320,7 +2333,7 @@
 			}
 
 			control.setting.bind( function ( value ) {
-				// bail if the update came from the control itself
+				// Bail if the update came from the control itself.
 				if ( updating ) {
 					return;
 				}
@@ -2641,6 +2654,7 @@
 		 * Set up control UI once embedded in DOM and settings are created.
 		 *
 		 * @since 4.7.0
+		 * @access public
 		 */
 		ready: function() {
 			var control = this, updateRadios;
@@ -3713,8 +3727,7 @@
 					parsedCandidateUrls.unshift( urlParser );
 				}
 
-				// Attempt to match the URL to the control frame's scheme
+				// Attempt to match the URL to the control frame's scheme and check if it's allowed. If not, try the original URL.
-				// and check if it's allowed. If not, try the original URL.
 				parsedAllowedUrl = document.createElement( 'a' );
 				_.find( parsedCandidateUrls, function( parsedCandidateUrl ) {
 					return ! _.isUndefined( _.find( previewer.allowedUrls, function( allowedUrl ) {
@@ -3771,6 +3784,7 @@
 		 * Handle the preview receiving the ready message.
 		 *
 		 * @since 4.7.0
+		 * @access public
 		 *
 		 * @param {object} data - Data from preview.
 		 * @param {string} data.currentUrl - Current URL.
@@ -3845,6 +3859,7 @@
 		 * If a message is not received in the allotted time then the iframe will be set back to the last known valid URL.
 		 *
 		 * @since 4.7.0
+		 * @access public
 		 *
 		 * @returns {void}
 		 */
@@ -3904,6 +3919,10 @@
 
 		/**
 		 * Refresh the preview seamlessly.
+		 *
+		 * @since 3.4.0
+		 * @access public
+		 * @returns {void}
 		 */
 		refresh: function() {
 			var previewer = this, onSettingChange;
@@ -4299,7 +4318,9 @@
 			/**
 			 * Build the query to send along with the Preview request.
 			 *
+			 * @since 3.4.0
 			 * @since 4.7.0 Added options param.
+			 * @access public
 			 *
 			 * @param {object}  [options] Options.
 			 * @param {boolean} [options.excludeCustomizedSaved=false] Exclude saved settings in customized response (values pending writing to changeset).
@@ -4333,12 +4354,14 @@
 			 * A revision will be made for the changeset post if revisions support
 			 * has been added to the post type.
 			 *
+			 * @since 3.4.0
+			 * @since 4.7.0 Added args param and return value.
+			 *
 			 * @param {object} [args] Args.
 			 * @param {string} [args.status=publish] Status.
 			 * @param {string} [args.date] Date, in local time in MySQL format.
 			 * @param {string} [args.title] Title
-			 *
+			 * @returns {jQuery.promise} Promise.
-			 * @returns {jQuery.promise}
 			 */
 			save: function( args ) {
 				var previewer = this,
@@ -4693,6 +4716,15 @@
 				}
 			});
 
+			/**
+			 * Populate URL with UUID via `history.replaceState()`.
+			 *
+			 * @since 4.7.0
+			 * @access private
+			 *
+			 * @param {boolean} isIncluded Is UUID included.
+			 * @returns {void}
+			 */
 			populateChangesetUuidParam = function( isIncluded ) {
 				var urlParser, queryParams;
 				urlParser = document.createElement( 'a' );
@@ -4829,7 +4861,15 @@
 				changeContainer, getHeaderHeight, releaseStickyHeader, resetStickyHeader, positionStickyHeader,
 				activeHeader, lastScrollTop;
 
-			// Determine which panel or section is currently expanded.
+			/**
+			 * Determine which panel or section is currently expanded.
+			 *
+			 * @since 4.7.0
+			 * @access private
+			 *
+			 * @param {wp.customize.Panel|wp.customize.Section} container Construct.
+			 * @returns {void}
+			 */
 			changeContainer = function( container ) {
 				var newInstance = container,
 					expandedSection = api.state( 'expandedSection' ).get(),
@@ -4905,7 +4945,15 @@
 				headerParent.css( 'padding-top', '' );
 			};
 
-			// Get header height.
+			/**
+			 * Get header height.
+			 *
+			 * @since 4.7.0
+			 * @access private
+			 *
+			 * @param {jQuery} headerElement Header element.
+			 * @returns {number} Height.
+			 */
 			getHeaderHeight = function( headerElement ) {
 				var height = headerElement.data( 'height' );
 				if ( ! height ) {
@@ -4915,7 +4963,17 @@
 				return height;
 			};
 
-			// Reposition header on throttled `scroll` event.
+			/**
+			 * Reposition header on throttled `scroll` event.
+			 *
+			 * @since 4.7.0
+			 * @access private
+			 *
+			 * @param {object}  header        Header.
+			 * @param {number}  scrollTop     Scroll top.
+			 * @param {boolean} isScrollingUp Is scrolling up?
+			 * @returns {void}
+			 */
 			positionStickyHeader = function( header, scrollTop, isScrollingUp ) {
 				var headerElement = header.element,
 					headerParent = header.parent,
@@ -5362,6 +5420,7 @@
 			/**
 			 * Request changeset update and then re-schedule the next changeset update time.
 			 *
+			 * @since 4.7.0
 			 * @private
 			 */
 			updateChangesetWithReschedule = function() {
@@ -5377,6 +5436,7 @@
 			/**
 			 * Schedule changeset update.
 			 *
+			 * @since 4.7.0
 			 * @private
 			 */
 			scheduleChangesetUpdate = function() {

wp-admin/js/customize-nav-menus.js

@@ -85,6 +85,9 @@
 	/**
 	 * Insert a new `auto-draft` post.
 	 *
+	 * @since 4.7.0
+	 * @access public
+	 *
 	 * @param {object} params - Parameters for the draft post to create.
 	 * @param {string} params.post_type - Post type to add.
 	 * @param {string} params.post_title - Post title to use.
@@ -562,7 +565,15 @@
 			itemName.val( '' );
 		},
 
-		// Submit handler for keypress (enter) on field and click on button.
+		/**
+		 * Submit handler for keypress (enter) on field and click on button.
+		 *
+		 * @since 4.7.0
+		 * @private
+		 *
+		 * @param {jQuery.Event} event Event.
+		 * @returns {void}
+		 */
 		_submitNew: function( event ) {
 			var container;
 
@@ -580,7 +591,15 @@
 			this.submitNew( container );
 		},
 
-		// Creates a new object and adds an associated menu item to the menu.
+		/**
+		 * Creates a new object and adds an associated menu item to the menu.
+		 *
+		 * @since 4.7.0
+		 * @private
+		 *
+		 * @param {jQuery} container
+		 * @returns {void}
+		 */
 		submitNew: function( container ) {
 			var panel = this,
 				itemName = container.find( '.create-item-input' ),

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

@@ -119,7 +119,7 @@ class WP_Customize_Control {
 	 *
 	 * @since 4.7.0
 	 * @access public
-	 * @var array
+	 * @var bool
 	 */
 	public $allow_addition = false;
 

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

@@ -3967,27 +3967,27 @@ final class WP_Customize_Manager {
 			if ( ! in_array( $value, array( 'repeat-x', 'repeat-y', 'repeat', 'no-repeat' ) ) ) {
 				return new WP_Error( 'invalid_value', __( 'Invalid value for background repeat.' ) );
 			}
-		} else if ( 'background_attachment' === $setting->id ) {
+		} elseif ( 'background_attachment' === $setting->id ) {
 			if ( ! in_array( $value, array( 'fixed', 'scroll' ) ) ) {
 				return new WP_Error( 'invalid_value', __( 'Invalid value for background attachment.' ) );
 			}
-		} else if ( 'background_position_x' === $setting->id ) {
+		} elseif ( 'background_position_x' === $setting->id ) {
 			if ( ! in_array( $value, array( 'left', 'center', 'right' ), true ) ) {
 				return new WP_Error( 'invalid_value', __( 'Invalid value for background position X.' ) );
 			}
-		} else if ( 'background_position_y' === $setting->id ) {
+		} elseif ( 'background_position_y' === $setting->id ) {
 			if ( ! in_array( $value, array( 'top', 'center', 'bottom' ), true ) ) {
 				return new WP_Error( 'invalid_value', __( 'Invalid value for background position Y.' ) );
 			}
-		} else if ( 'background_size' === $setting->id ) {
+		} elseif ( 'background_size' === $setting->id ) {
 			if ( ! in_array( $value, array( 'auto', 'contain', 'cover' ), true ) ) {
 				return new WP_Error( 'invalid_value', __( 'Invalid value for background size.' ) );
 			}
-		} else if ( 'background_preset' === $setting->id ) {
+		} elseif ( 'background_preset' === $setting->id ) {
 			if ( ! in_array( $value, array( 'default', 'fill', 'fit', 'repeat', 'custom' ), true ) ) {
 				return new WP_Error( 'invalid_value', __( 'Invalid value for background size.' ) );
 			}
-		} else if ( 'background_image' === $setting->id || 'background_image_thumb' === $setting->id ) {
+		} elseif ( 'background_image' === $setting->id || 'background_image_thumb' === $setting->id ) {
 			$value = empty( $value ) ? '' : esc_url_raw( $value );
 		} else {
 			return new WP_Error( 'unrecognized_setting', __( 'Unrecognized background setting.' ) );

wp-includes/customize/class-wp-customize-color-control.php

@@ -16,18 +16,25 @@
  */
 class WP_Customize_Color_Control extends WP_Customize_Control {
 	/**
+	 * Type.
+	 *
 	 * @access public
 	 * @var string
 	 */
 	public $type = 'color';
 
 	/**
+	 * Statuses.
+	 *
 	 * @access public
 	 * @var array
 	 */
 	public $statuses;
 
 	/**
+	 * Mode.
+	 *
+	 * @since 4.7.0
 	 * @access public
 	 * @var string
 	 */

wp-includes/customize/class-wp-customize-custom-css-setting.php

@@ -21,10 +21,9 @@ final class WP_Customize_Custom_CSS_Setting extends WP_Customize_Setting {
 	/**
 	 * The setting type.
 	 *
-	 * @var string
-	 *
 	 * @since 4.7.0
 	 * @access public
+	 * @var string
 	 */
 	public $type = 'custom_css';
 
@@ -33,7 +32,6 @@ final class WP_Customize_Custom_CSS_Setting extends WP_Customize_Setting {
 	 *
 	 * @since 4.7.0
 	 * @access public
-	 *
 	 * @var string
 	 */
 	public $transport = 'postMessage';
@@ -43,7 +41,6 @@ final class WP_Customize_Custom_CSS_Setting extends WP_Customize_Setting {
 	 *
 	 * @since 4.7.0
 	 * @access public
-	 *
 	 * @var string
 	 */
 	public $capability = 'edit_css';
@@ -53,7 +50,6 @@ final class WP_Customize_Custom_CSS_Setting extends WP_Customize_Setting {
 	 *
 	 * @since 4.7.0
 	 * @access public
-	 *
 	 * @var string
 	 */
 	public $stylesheet = '';

wp-includes/customize/class-wp-customize-nav-menu-item-setting.php

@@ -267,6 +267,7 @@ class WP_Customize_Nav_Menu_Item_Setting extends WP_Customize_Setting {
 	 * Get original title.
 	 *
 	 * @since 4.7.0
+	 * @access protected
 	 *
 	 * @param object $item Nav menu item.
 	 * @return string The original title.

wp-includes/js/customize-preview.js

@@ -132,6 +132,7 @@
 		 * Handle link clicks in preview.
 		 *
 		 * @since 4.7.0
+		 * @access public
 		 *
 		 * @param {jQuery.Event} event Event.
 		 */
@@ -178,6 +179,7 @@
 		 * Handle form submit.
 		 *
 		 * @since 4.7.0
+		 * @access public
 		 *
 		 * @param {jQuery.Event} event Event.
 		 */

wp-includes/js/customize-selective-refresh.js

@@ -104,6 +104,7 @@ wp.customize.selectiveRefresh = ( function( $, api ) {
 		 * Create and show the edit shortcut for a given partial placement container.
 		 *
 		 * @since 4.7.0
+		 * @access public
 		 *
 		 * @param {Placement} placement The placement container element.
 		 * @returns {void}
@@ -132,6 +133,7 @@ wp.customize.selectiveRefresh = ( function( $, api ) {
 		 * Add an edit shortcut to the placement container.
 		 *
 		 * @since 4.7.0
+		 * @access public
 		 *
 		 * @param {Placement} placement The placement for the partial.
 		 * @param {jQuery} $editShortcut The shortcut element as a jQuery object.
@@ -149,6 +151,7 @@ wp.customize.selectiveRefresh = ( function( $, api ) {
 		 * Return the unique class name for the edit shortcut button for this partial.
 		 *
 		 * @since 4.7.0
+		 * @access public
 		 *
 		 * @return {string} Partial ID converted into a class name for use in shortcut.
 		 */
@@ -162,6 +165,7 @@ wp.customize.selectiveRefresh = ( function( $, api ) {
 		 * Return the appropriate translated string for the edit shortcut button.
 		 *
 		 * @since 4.7.0
+		 * @access public
 		 *
 		 * @return {string} Tooltip for edit shortcut.
 		 */
@@ -187,6 +191,7 @@ wp.customize.selectiveRefresh = ( function( $, api ) {
 		 * Will use `params.type` if set, but otherwise will try to infer type from settingId.
 		 *
 		 * @since 4.7.0
+		 * @access public
 		 *
 		 * @return {string} Type of partial derived from type param or the related setting ID.
 		 */
@@ -209,6 +214,7 @@ wp.customize.selectiveRefresh = ( function( $, api ) {
 		 * Create an edit shortcut button for this partial.
 		 *
 		 * @since 4.7.0
+		 * @access public
 		 *
 		 * @return {jQuery} The edit shortcut button element.
 		 */

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.7-beta4-39344';
+$wp_version = '4.7-beta4-39345';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.