WordPress.org
Get WordPress

Make WordPress Core

Changeset 42416


Ignore:
Timestamp:
12/21/2017 03:11:25 PM (7 years ago)
Author:
atimmer
Message:

Docs: Improve JSDoc for customize-preview-widgets.js.

Props ireneyoast, andizer, robinvandervliet, boblinthorst.
Fixes #42954.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/js/customize-preview-widgets.js

    r41872 r42416  
    11/* global _wpWidgetCustomizerPreviewSettings */
    22
    3 /** @namespace wp.customize.widgetsPreview */
     3/**
     4 * Handles the initialization, refreshing and rendering of widget partials and sidebar widgets.
     5 *
     6 * @since 4.5.0
     7 *
     8 * @namespace wp.customize.widgetsPreview
     9 *
     10 * @param {jQuery} $   The jQuery object.
     11 * @param {Object} _   The utilities library.
     12 * @param {Object} wp  Current WordPress environment instance.
     13 * @param {Object} api Information from the API.
     14 *
     15 * @returns {Object} Widget-related variables.
     16 */
    417wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function( $, _, wp, api ) {
    518
    … …  
    2033
    2134    /**
    22      * Init widgets preview.
     35     * Initializes the widgets preview.
    2336     *
    2437     * @since 4.5.0
     38     *
     39     * @memberOf wp.customize.widgetsPreview
     40     *
     41     * @returns {void}
    2542     */
    2643    self.init = function() {
    … …  
    6077    };
    6178
    62     /**
    63      * Partial representing a widget instance.
    64      *
    65      * @memberOf wp.customize.widgetsPreview
    66      * @alias wp.customize.widgetsPreview.WidgetPartial
    67      *
    68      * @class
    69      * @augments wp.customize.selectiveRefresh.Partial
    70      * @since 4.5.0
    71      */
    7279    self.WidgetPartial = api.selectiveRefresh.Partial.extend(/** @lends wp.customize.widgetsPreview.WidgetPartial.prototype */{
    7380
    7481        /**
    75          * Constructor.
    76          *
    77          * @since 4.5.0
    78          * @param {string} id - Partial ID.
    79          * @param {Object} options
    80          * @param {Object} options.params
     82         * Represents a partial widget instance.
     83         *
     84         * @since 4.5.0
     85         *
     86         * @constructs
     87         * @augments wp.customize.selectiveRefresh.Partial
     88         *
     89         * @alias wp.customize.widgetsPreview.WidgetPartial
     90         * @memberOf wp.customize.widgetsPreview
     91         *
     92         * @param {string} id             The partial's ID.
     93         * @param {Object} options        Options used to initialize the partial's
     94         *                                instance.
     95         * @param {Object} options.params The options parameters.
    8196         */
    8297        initialize: function( id, options ) {
    … …  
    102117
    103118        /**
    104          * Refresh widget partial.
    105          *
    106          * @returns {Promise}
     119         * Refreshes the widget partial.
     120         *
     121         * @since 4.5.0
     122         *
     123         * @returns {Promise|void} Either a promise postponing the refresh, or void.
    107124         */
    108125        refresh: function() {
    … …  
    119136
    120137        /**
    121          * Send widget-updated message to parent so spinner will get removed from widget control.
    122          *
    123          * @inheritdoc
    124          * @param {wp.customize.selectiveRefresh.Placement} placement
     138         * Sends the widget-updated message to the parent so the spinner will get
     139         * removed from the widget control.
     140         *
     141         * @inheritDoc
     142         * @param {wp.customize.selectiveRefresh.Placement} placement The placement
     143         *                                                            function.
     144         *
     145         * @returns {void}
    125146         */
    126147        renderContent: function( placement ) {
    … …  
    133154    });
    134155
    135     /**
    136      * Partial representing a widget area.
    137      *
    138      * @memberOf wp.customize.widgetsPreview
    139      * @alias wp.customize.widgetsPreview.SidebarPartial
    140      *
    141      * @class
    142      * @augments wp.customize.selectiveRefresh.Partial
    143      * @since 4.5.0
    144      */
    145156    self.SidebarPartial = api.selectiveRefresh.Partial.extend(/** @lends wp.customize.widgetsPreview.SidebarPartial.prototype */{
    146157
    147158        /**
    148          * Constructor.
    149          *
    150          * @since 4.5.0
    151          * @param {string} id - Partial ID.
    152          * @param {Object} options
    153          * @param {Object} options.params
     159         * Represents a partial widget area.
     160         *
     161         * @since 4.5.0
     162         *
     163         * @class
     164         * @augments wp.customize.selectiveRefresh.Partial
     165         *
     166         * @memberOf wp.customize.widgetsPreview
     167         * @alias wp.customize.widgetsPreview.SidebarPartial
     168         *
     169         * @param {string} id             The partial's ID.
     170         * @param {Object} options        Options used to initialize the partial's instance.
     171         * @param {Object} options.params The options parameters.
    154172         */
    155173        initialize: function( id, options ) {
    … …  
    180198
    181199        /**
    182          * Set up the partial.
    183          *
    184          * @since 4.5.0
     200         * Sets up the partial.
     201         *
     202         * @since 4.5.0
     203         *
     204         * @returns {void}
    185205         */
    186206        ready: function() {
    … …  
    221241
    222242        /**
    223          * Get the before/after boundary nodes for all instances of this sidebar (usually one).
     243         * Gets the before/after boundary nodes for all instances of this sidebar
     244         * (usually one).
    224245         *
    225246         * Note that TreeWalker is not implemented in IE8.
    226247         *
    227248         * @since 4.5.0
     249         *
    228250         * @returns {Array.<{before: Comment, after: Comment, instanceNumber: number}>}
     251         *          An array with an object for each sidebar instance, containing the
     252         *          node before and after the sidebar instance and its instance number.
    229253         */
    230254        findDynamicSidebarBoundaryNodes: function() {
    … …  
    262286
    263287        /**
    264          * Get the placements for this partial.
    265          *
    266          * @since 4.5.0
    267          * @returns {Array}
     288         * Gets the placements for this partial.
     289         *
     290         * @since 4.5.0
     291         *
     292         * @returns {Array} An array containing placement objects for each of the
     293         *                  dynamic sidebar boundary nodes.
    268294         */
    269295        placements: function() {
    … …  
    287313         * @since 4.5.0
    288314         *
    289          * @returns {Array}
     315         * @throws {Error} If there's no settingId.
     316         * @throws {Error} If the setting doesn't exist in the API.
     317         * @throws {Error} If the API doesn't pass an array of widget ids.
     318         *
     319         * @returns {Array} A shallow copy of the array containing widget IDs.
    290320         */
    291321        getWidgetIds: function() {
    … …  
    306336
    307337        /**
    308          * Reflow widgets in the sidebar, ensuring they have the proper position in the DOM.
    309          *
    310          * @since 4.5.0
    311          *
    312          * @return {Array.<wp.customize.selectiveRefresh.Placement>} List of placements that were reflowed.
     338         * Reflows widgets in the sidebar, ensuring they have the proper position in the
     339         * DOM.
     340         *
     341         * @since 4.5.0
     342         *
     343         * @returns {Array.<wp.customize.selectiveRefresh.Placement>} List of placements
     344         *                                                            that were reflowed.
    313345         */
    314346        reflowWidgets: function() {
    … …  
    370402
    371403        /**
    372          * Make sure there is a widget instance container in this sidebar for the given widget ID.
    373          *
    374          * @since 4.5.0
    375          *
    376          * @param {string} widgetId
    377          * @returns {wp.customize.selectiveRefresh.Partial} Widget instance partial.
     404         * Makes sure there is a widget instance container in this sidebar for the given
     405         * widget ID.
     406         *
     407         * @since 4.5.0
     408         *
     409         * @param {string} widgetId The widget ID.
     410         *
     411         * @returns {wp.customize.selectiveRefresh.Partial} The widget instance partial.
    378412         */
    379413        ensureWidgetPlacementContainers: function( widgetId ) {
    … …  
    436470
    437471        /**
    438          * Handle change to the sidebars_widgets[] setting.
    439          *
    440          * @since 4.5.0
    441          *
    442          * @param {Array} newWidgetIds New widget ids.
    443          * @param {Array} oldWidgetIds Old widget ids.
     472         * Handles changes to the sidebars_widgets[] setting.
     473         *
     474         * @since 4.5.0
     475         *
     476         * @param {Array} newWidgetIds New widget IDs.
     477         * @param {Array} oldWidgetIds Old widget IDs.
     478         *
     479         * @returns {void}
    444480         */
    445481        handleSettingChange: function( newWidgetIds, oldWidgetIds ) {
    … …  
    489525
    490526        /**
    491          * Note that the meat is handled in handleSettingChange because it has the context of which widgets were removed.
    492          *
    493          * @since 4.5.0
     527         * Refreshes the sidebar partial.
     528         *
     529         * Note that the meat is handled in handleSettingChange because it has the
     530         * context of which widgets were removed.
     531         *
     532         * @since 4.5.0
     533         *
     534         * @returns {Promise} A promise postponing the refresh.
    494535         */
    495536        refresh: function() {
    … …  
    517558
    518559    /**
    519      * Add partials for the registered widget areas (sidebars).
     560     * Adds partials for the registered widget areas (sidebars).
    520561     *
    521562     * @since 4.5.0
     563     *
     564     * @returns {void}
    522565     */
    523566    self.addPartials = function() {
    … …  
    537580
    538581    /**
    539      * Calculate the selector for the sidebar's widgets based on the registered sidebar's info.
     582     * Calculates the selector for the sidebar's widgets based on the registered
     583     * sidebar's info.
    540584     *
    541585     * @memberOf wp.customize.widgetsPreview
    542586     *
    543587     * @since 3.9.0
     588     *
     589     * @returns {void}
    544590     */
    545591    self.buildWidgetSelectors = function() {
    … …  
    577623
    578624    /**
    579      * Highlight the widget on widget updates or widget control mouse overs.
     625     * Highlights the widget on widget updates or widget control mouse overs.
    580626     *
    581627     * @memberOf wp.customize.widgetsPreview
    … …  
    583629     * @since 3.9.0
    584630     * @param  {string} widgetId ID of the widget.
     631     *
     632     * @returns {void}
    585633     */
    586634    self.highlightWidget = function( widgetId ) {
    … …  
    597645
    598646    /**
    599      * Show a title and highlight widgets on hover. On shift+clicking
    600      * focus the widget control.
     647     * Shows a title and highlights widgets on hover. On shift+clicking focuses the
     648     * widget control.
    601649     *
    602650     * @memberOf wp.customize.widgetsPreview
    603651     *
    604652     * @since 3.9.0
     653     *
     654     * @returns {void}
    605655     */
    606656    self.highlightControls = function() {
    … …  
    614664
    615665        $( selector ).attr( 'title', this.l10n.widgetTooltip );
    616 
     666        // Highlights widget when entering the widget editor.
    617667        $( document ).on( 'mouseenter', selector, function() {
    618668            self.preview.send( 'highlight-widget-control', $( this ).prop( 'id' ) );
    … …  
    631681
    632682    /**
    633      * Parse a widget ID.
     683     * Parses a widget ID.
    634684     *
    635685     * @memberOf wp.customize.widgetsPreview
    … …  
    637687     * @since 4.5.0
    638688     *
    639      * @param {string} widgetId Widget ID.
    640      * @returns {{idBase: string, number: number|null}}
     689     * @param {string} widgetId The widget ID.
     690     *
     691     * @returns {{idBase: string, number: number|null}} An object containing the
     692     *          idBase and number of the parsed widget ID.
    641693     */
    642694    self.parseWidgetId = function( widgetId ) {
    … …  
    658710
    659711    /**
    660      * Parse a widget setting ID.
     712     * Parses a widget setting ID.
    661713     *
    662714     * @memberOf wp.customize.widgetsPreview
    … …  
    665717     *
    666718     * @param {string} settingId Widget setting ID.
    667      * @returns {{idBase: string, number: number|null}|null}
     719     *
     720     * @returns {{idBase: string, number: number|null}|null} Either an object
     721     *          containing the idBase and number of the parsed widget setting ID, or
     722     *          null.
    668723     */
    669724    self.parseWidgetSettingId = function( settingId ) {
    … …  
    685740
    686741    /**
    687      * Convert a widget ID into a Customizer setting ID.
     742     * Converts a widget ID into a Customizer setting ID.
    688743     *
    689744     * @memberOf wp.customize.widgetsPreview
    … …  
    691746     * @since 4.5.0
    692747     *
    693      * @param {string} widgetId Widget ID.
    694      * @returns {string} settingId Setting ID.
     748     * @param {string} widgetId The widget ID.
     749     *
     750     * @returns {string} The setting ID.
    695751     */
    696752    self.getWidgetSettingId = function( widgetId ) {
Note: See TracChangeset for help on using the changeset viewer.