WordPress.org
Get WordPress

Make WordPress Core

Changeset 30738


Ignore:
Timestamp:
12/04/2014 02:03:30 AM (12 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.