WordPress.org

Make WordPress Core

Changeset 33841


Ignore:
Timestamp:
09/01/2015 04:14:50 AM (5 years ago)
Author:
wonderboymusic
Message:

Add some JS docs to customize-base.js

Props ericlewis.
Fixes #33639.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/js/customize-base.js

    r31893 r33841  
    7575
    7676        magic = this;
     77
     78        /*
     79         * If the class has a method called "instance",
     80         * the return value from the class' constructor will be a function that
     81         * calls invoked, along with all the object properties of the class.
     82         */
    7783        if ( this.instance ) {
    7884            magic = function() {
     
    102108    api.Class.applicator = {};
    103109
     110    /**
     111     * Initialize a class instance.
     112     *
     113     * Override this function in a subclass as needed.
     114     */
    104115    api.Class.prototype.initialize = function() {};
    105116
     
    282293        },
    283294
     295        /**
     296         * Get the instance of an item from the collection if only ID is specified.
     297         *
     298         * If more than one argument is supplied, all are expected to be IDs and
     299         * the last to be a function callback that will be invoked when the requested
     300         * items are available.
     301         *
     302         * @see {api.Values.when}
     303         *
     304         * @param  {string}   id ID of the item.
     305         * @param  {...}         Zero or more IDs of items to wait for and a callback
     306         *                       function to invoke when they're available. Optional.
     307         * @return {mixed}    The item instance if only one ID was supplied.
     308         *                    A Deferred Promise object if a callback function is supplied.
     309         */
    284310        instance: function( id ) {
    285311            if ( arguments.length === 1 )
     
    289315        },
    290316
     317        /**
     318         * Get the instance of an item.
     319         *
     320         * @param  {string} id The ID of the item.
     321         * @return {[type]}    [description]
     322         */
    291323        value: function( id ) {
    292324            return this._value[ id ];
    293325        },
    294326
     327        /**
     328         * Whether the collection has an item with the given ID.
     329         *
     330         * @param  {string}  id The ID of the item to look for.
     331         * @return {Boolean}
     332         */
    295333        has: function( id ) {
    296334            return typeof this._value[ id ] !== 'undefined';
    297335        },
    298336
     337        /**
     338         * Add an item to the collection.
     339         *
     340         * @param {string} id    The ID of the item.
     341         * @param {mixed}  value The item instance.
     342         * @return {mixed} The new item's instance.
     343         */
    299344        add: function( id, value ) {
    300345            if ( this.has( id ) )
     
    308353            this.trigger( 'add', value );
    309354
     355            // If a deferred object exists for this item,
     356            // resolve it.
    310357            if ( this._deferreds[ id ] )
    311358                this._deferreds[ id ].resolve();
     
    314361        },
    315362
     363        /**
     364         * Create a new item of the collection using the collection's default constructor
     365         * and store it in the collection.
     366         *
     367         * @param  {string} id    The ID of the item.
     368         * @param  {mixed}  value Any extra arguments are passed into the item's initialize method.
     369         * @return {mixed}  The new item's instance.
     370         */
    316371        create: function( id ) {
    317372            return this.add( id, new this.defaultConstructor( api.Class.applicator, slice.call( arguments, 1 ) ) );
     
    326381        },
    327382
     383        /**
     384         * Remove an item from the collection.
     385         *
     386         * @param  {string} id The ID of the item to remove.
     387         */
    328388        remove: function( id ) {
    329389            var value;
     
    360420                dfd.done( ids.pop() );
    361421
     422            /*
     423             * Create a stack of deferred objects for each item that is not
     424             * yet available, and invoke the supplied callback when they are.
     425             */
    362426            $.when.apply( $, $.map( ids, function( id ) {
    363427                if ( self.has( id ) )
    364428                    return;
    365429
     430                /*
     431                 * The requested item is not available yet, create a deferred
     432                 * object to resolve when it becomes available.
     433                 */
    366434                return self._deferreds[ id ] = self._deferreds[ id ] || $.Deferred();
    367435            })).done( function() {
Note: See TracChangeset for help on using the changeset viewer.