diff --git a/src/wp-admin/js/customize-controls.js b/src/wp-admin/js/customize-controls.js index 3de502e1d8..b79cd2a294 100644 --- a/src/wp-admin/js/customize-controls.js +++ b/src/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 - // and check if it's allowed. If not, try the original URL. + // Attempt to match the URL to the control frame's scheme 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} + * @returns {jQuery.promise} 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() { diff --git a/src/wp-admin/js/customize-nav-menus.js b/src/wp-admin/js/customize-nav-menus.js index 5e4e5f9056..be3fba1c46 100644 --- a/src/wp-admin/js/customize-nav-menus.js +++ b/src/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' ), diff --git a/src/wp-includes/class-wp-customize-control.php b/src/wp-includes/class-wp-customize-control.php index 40e10dca78..07c6dcfce1 100644 --- a/src/wp-includes/class-wp-customize-control.php +++ b/src/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; diff --git a/src/wp-includes/class-wp-customize-manager.php b/src/wp-includes/class-wp-customize-manager.php index 439e2b5305..e71787c676 100644 --- a/src/wp-includes/class-wp-customize-manager.php +++ b/src/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.' ) ); diff --git a/src/wp-includes/customize/class-wp-customize-color-control.php b/src/wp-includes/customize/class-wp-customize-color-control.php index e29b2e4b89..7f6a9b5a84 100644 --- a/src/wp-includes/customize/class-wp-customize-color-control.php +++ b/src/wp-includes/customize/class-wp-customize-color-control.php @@ -16,21 +16,28 @@ */ class WP_Customize_Color_Control extends WP_Customize_Control { /** + * Type. + * * @access public * @var string */ public $type = 'color'; /** + * Statuses. + * * @access public * @var array */ public $statuses; /** - * @access public - * @var string - */ + * Mode. + * + * @since 4.7.0 + * @access public + * @var string + */ public $mode = 'full'; /** diff --git a/src/wp-includes/customize/class-wp-customize-custom-css-setting.php b/src/wp-includes/customize/class-wp-customize-custom-css-setting.php index eadd47c581..f43859a18d 100644 --- a/src/wp-includes/customize/class-wp-customize-custom-css-setting.php +++ b/src/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 = ''; diff --git a/src/wp-includes/customize/class-wp-customize-nav-menu-item-setting.php b/src/wp-includes/customize/class-wp-customize-nav-menu-item-setting.php index 00d69527b9..8bffb0ee2a 100644 --- a/src/wp-includes/customize/class-wp-customize-nav-menu-item-setting.php +++ b/src/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. diff --git a/src/wp-includes/js/customize-preview.js b/src/wp-includes/js/customize-preview.js index 7a37ba5f38..a4cb196dc1 100644 --- a/src/wp-includes/js/customize-preview.js +++ b/src/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. */ diff --git a/src/wp-includes/js/customize-selective-refresh.js b/src/wp-includes/js/customize-selective-refresh.js index 75006a7a99..f6dfa0b9d8 100644 --- a/src/wp-includes/js/customize-selective-refresh.js +++ b/src/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. */