WordPress.org
Get WordPress

Make WordPress Core

Changeset 30738


Ignore:
Timestamp:
12/04/2014 02:03:30 AM (10 years ago)
Author:
wonderboymusic
Message:

Add some inline JS docs for Customizer.

See #30469.

Location:
trunk/src/wp-admin/js
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-admin/js/common.js

    r30352 r30738  
    248248    });
    249249
     250    /**
     251     * Ensure an admin submenu is within the visual viewport.
     252     *
     253     * @since 4.1.0
     254     *
     255     * @param {jQuery} $menuItem The parent menu item containing the submenu.
     256     */
    250257    function adjustSubmenu( $menuItem ) {
    251258        var bottomOffset, pageHeight, adjustment, theFold, menutop, wintop, maxtop,

  • trunk/src/wp-admin/js/customize-controls.js

    r30716 r30738  
    3939     * Watch all changes to Value properties, and bubble changes to parent Values instance
    4040     *
     41     * @since 4.1.0
     42     *
    4143     * @param {wp.customize.Class} instance
    42      * @param {Array} properties  The names of the Value instances to watch.
     44     * @param {Array}              properties  The names of the Value instances to watch.
    4345     */
    4446    api.utils.bubbleChildValueChanges = function ( instance, properties ) {
    … …  
    5557     * Expand a panel, section, or control and focus on the first focusable element.
    5658     *
    57      * @param {Object} [params]
     59     * @since 4.1.0
     60     *
     61     * @param {Object}   [params]
     62     * @param {Callback} [params.completeCallback]
    5863     */
    5964    focus = function ( params ) {
    … …  
    8691     * If a.priority() === b.priority(), then sort by their respective params.instanceNumber.
    8792     *
     93     * @since 4.1.0
     94     *
    8895     * @param {(wp.customize.Panel|wp.customize.Section|wp.customize.Control)} a
    8996     * @param {(wp.customize.Panel|wp.customize.Section|wp.customize.Control)} b
    … …  
    101108     * Return whether the supplied Event object is for a keydown event but not the Enter key.
    102109     *
     110     * @since 4.1.0
     111     *
    103112     * @param {jQuery.Event} event
    104113     * @returns {boolean}
    … …  
    110119    /**
    111120     * Return whether the two lists of elements are the same and are in the same order.
     121     *
     122     * @since 4.1.0
    112123     *
    113124     * @param {Array|jQuery} listA
    … …  
    129140
    130141    /**
    131      * Base class for Panel and Section
     142     * Base class for Panel and Section.
     143     *
     144     * @since 4.1.0
    132145     *
    133146     * @class
    … …  
    138151        defaultExpandedArguments: { duration: 'fast', completeCallback: $.noop },
    139152
     153        /**
     154         * @since 4.1.0
     155         *
     156         * @param {String} id
     157         * @param {Object} options
     158         */
    140159        initialize: function ( id, options ) {
    141160            var container = this;
    … …  
    176195
    177196        /**
     197         * @since 4.1.0
     198         *
    178199         * @abstract
    179200         */
    … …  
    182203        /**
    183204         * Get the child models associated with this parent, sorting them by their priority Value.
     205         *
     206         * @since 4.1.0
    184207         *
    185208         * @param {String} parentType
    … …  
    201224        /**
    202225         * To override by subclass, to return whether the container has active children.
     226         *
     227         * @since 4.1.0
     228         *
    203229         * @abstract
    204230         */
    … …  
    209235        /**
    210236         * Handle changes to the active state.
     237         *
    211238         * This does not change the active state, it merely handles the behavior
    212239         * for when it does change.
    … …  
    214241         * To override by subclass, update the container's UI to reflect the provided active state.
    215242         *
     243         * @since 4.1.0
     244         *
    216245         * @param {Boolean} active
    217          * @param {Object} args  merged on top of this.defaultActiveArguments
     246         * @param {Object}  args
     247         * @param {Object}  args.duration
     248         * @param {Object}  args.completeCallback
    218249         */
    219250        onChangeActive: function ( active, args ) {
    … …  
    231262
    232263        /**
     264         * @since 4.1.0
     265         *
    233266         * @params {Boolean} active
    234          * @param {Object} [params]
     267         * @param {Object}   [params]
    235268         * @returns {Boolean} false if state already applied
    236269         */
    … …  
    318351
    319352    /**
     353     * @since 4.1.0
     354     *
    320355     * @class
    321356     * @augments wp.customize.Class
    … …  
    324359
    325360        /**
     361         * @since 4.1.0
     362         *
    326363         * @param {String} id
    327          * @param {Array} options
     364         * @param {Array}  options
    328365         */
    329366        initialize: function ( id, options ) {
    … …  
    347384        /**
    348385         * Embed the container in the DOM when any parent panel is ready.
     386         *
     387         * @since 4.1.0
    349388         */
    350389        embed: function () {
    … …  
    380419
    381420        /**
    382          * Add behaviors for the accordion section
     421         * Add behaviors for the accordion section.
     422         *
     423         * @since 4.1.0
    383424         */
    384425        attachEvents: function () {
    … …  
    403444         * Return whether this section has any active controls.
    404445         *
    405          * @returns {boolean}
     446         * @since 4.1.0
     447         *
     448         * @returns {Boolean}
    406449         */
    407450        isContextuallyActive: function () {
    … …  
    420463         * Get the controls that are associated with this section, sorted by their priority Value.
    421464         *
     465         * @since 4.1.0
     466         *
    422467         * @returns {Array}
    423468         */
    … …  
    427472
    428473        /**
    429          * Update UI to reflect expanded state
     474         * Update UI to reflect expanded state.
     475         *
     476         * @since 4.1.0
    430477         *
    431478         * @param {Boolean} expanded
    432          * @param {Object} args
     479         * @param {Object}  args
    433480         */
    434481        onChangeExpanded: function ( expanded, args ) {
    … …  
    473520
    474521    /**
     522     * @since 4.1.0
     523     *
    475524     * @class
    476525     * @augments wp.customize.Class
    477526     */
    478527    api.Panel = Container.extend({
     528        /**
     529         * @since 4.1.0
     530         *
     531         * @param  {String} id
     532         * @param  {Object} options
     533         */
    479534        initialize: function ( id, options ) {
    480535            var panel = this;
    … …  
    488543        /**
    489544         * Embed the container in the DOM when any parent panel is ready.
     545         *
     546         * @since 4.1.0
    490547         */
    491548        embed: function () {
    … …  
    500557
    501558        /**
    502          *
     559         * @since 4.1.0
    503560         */
    504561        attachEvents: function () {
    … …  
    544601         * Get the sections that are associated with this panel, sorted by their priority Value.
    545602         *
     603         * @since 4.1.0
     604         *
    546605         * @returns {Array}
    547606         */
    … …  
    552611        /**
    553612         * Return whether this panel has any active sections.
     613         *
     614         * @since 4.1.0
    554615         *
    555616         * @returns {boolean}
    … …  
    570631         * Update UI to reflect expanded state
    571632         *
    572          * @param {Boolean} expanded
    573          * @param {Object} args  merged with this.defaultExpandedArguments
     633         * @since 4.1.0
     634         *
     635         * @param {Boolean}  expanded
     636         * @param {Object}   args
     637         * @param {Boolean}  args.unchanged
     638         * @param {Callback} args.completeCallback
    574639         */
    575640        onChangeExpanded: function ( expanded, args ) {
    … …  
    793858
    794859        /**
    795          * Bring the containing section and panel into view and then this control into view, focusing on the first input
     860         * Bring the containing section and panel into view and then
     861         * this control into view, focusing on the first input.
    796862         */
    797863        focus: focus,
    … …  
    802868         * for when it does change.
    803869         *
    804          * @param {Boolean} active
    805          * @param {Object} args  merged on top of this.defaultActiveArguments
     870         * @since 4.1.0
     871         *
     872         * @param {Boolean}  active
     873         * @param {Object}   args
     874         * @param {Number}   args.duration
     875         * @param {Callback} args.completeCallback
    806876         */
    807877        onChangeActive: function ( active, args ) {
    … …  
    818888
    819889        /**
    820          * @deprecated alias of onChangeActive
     890         * @deprecated 4.1.0 Use this.onChangeActive() instead.
    821891         */
    822892        toggle: function ( active ) {
    … …  
    827897         * Shorthand way to enable the active state.
    828898         *
     899         * @since 4.1.0
     900         *
    829901         * @param {Object} [params]
    830902         * @returns {Boolean} false if already active
    … …  
    834906        /**
    835907         * Shorthand way to disable the active state.
     908         *
     909         * @since 4.1.0
    836910         *
    837911         * @param {Object} [params]
    … …  
    881955         *
    882956         * The control's container must already exist in the DOM.
     957         *
     958         * @since 4.1.0
    883959         */
    884960        renderContent: function () {
    … …  
    12921368    api.defaultConstructor = api.Setting;
    12931369
    1294     // Create the collection of Control objects.
     1370    // Create the collections for Controls, Sections and Panels.
    12951371    api.control = new api.Values({ defaultConstructor: api.Control });
    12961372    api.section = new api.Values({ defaultConstructor: api.Section });
    … …  
    14961572
    14971573    /**
    1498      * Set the document title of the customizer
     1574     * Set the document title of the customizer.
     1575     *
     1576     * @since 4.1.0
    14991577     *
    15001578     * @param {string} documentTitle
    … …  
    16291707            this.bind( 'url', this.previewUrl );
    16301708
    1631             // Update the document title when the preview changes
     1709            // Update the document title when the preview changes.
    16321710            this.bind( 'documentTitle', function ( title ) {
    16331711                api.setDocumentTitle( title );
    … …  
    17691847        });
    17701848
    1771         // Expand/Collapse the main customizer customize info
     1849        // Expand/Collapse the main customizer customize info.
    17721850        $( '#customize-info' ).find( '> .accordion-section-title' ).on( 'click keydown', function( event ) {
    17731851            if ( api.utils.isKeydownButNotEnterEvent( event ) ) {
    … …  
    19442022        /**
    19452023         * Sort panels, sections, controls by priorities. Hide empty sections and panels.
     2024         *
     2025         * @since 4.1.0
    19462026         */
    19472027        api.reflowPaneContents = _.bind( function () {

  • trunk/src/wp-admin/js/customize-widgets.js

    r30552 r30738  
    410410        },
    411411
     412        /**
     413         * @since 4.1.0
     414         */
    412415        initialize: function ( id, options ) {
    413416            var control = this;
    … …  
    801804         * Overrides api.Control.toggle()
    802805         *
    803          * @param {Boolean} active
    804          * @param {Object} args
     806         * @since 4.1.0
     807         *
     808         * @param {Boolean}   active
     809         * @param {Object}    args
     810         * @param {Callback}  args.completeCallback
    805811         */
    806812        onChangeActive: function ( active, args ) {
    … …  
    11351141
    11361142        /**
     1143         * @since 4.1.0
     1144         *
    11371145         * @param {Boolean} expanded
    11381146         * @param {Object} [params]
    … …  
    11421150
    11431151        /**
     1152         * @since 4.1.0
     1153         *
    11441154         * @param {Object} [params]
    11451155         * @returns {Boolean} false if already expanded
    … …  
    11501160         * Expand the widget form control
    11511161         *
    1152          * @deprecated alias of expand()
     1162         * @deprecated 4.1.0 Use this.expand() instead.
    11531163         */
    11541164        expandForm: function() {
    … …  
    11571167
    11581168        /**
     1169         * @since 4.1.0
     1170         *
    11591171         * @param {Object} [params]
    11601172         * @returns {Boolean} false if already collapsed
    … …  
    11651177         * Collapse the widget form control
    11661178         *
    1167          * @deprecated alias of expand()
     1179         * @deprecated 4.1.0 Use this.collapse() instead.
    11681180         */
    11691181        collapseForm: function() {
    … …  
    13791391        /**
    13801392         * Sync the section's active state back to the Backbone model's is_rendered attribute
     1393         *
     1394         * @since 4.1.0
    13811395         */
    13821396        ready: function () {
Note: See TracChangeset for help on using the changeset viewer.