WordPress.org

Make WordPress Core

Changeset 28688


Ignore:
Timestamp:
06/06/14 14:12:03 (3 years ago)
Author:
wonderboymusic
Message:

Improve inline doc descriptions in media-views.js.

Props ericlewis.
See #28459.

Location:
trunk/src/wp-includes/js
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/js/media-models.js

    r28682 r28688  
    66 
    77    /** 
    8      * wp.media( attributes ) 
     8     * Create and return a media frame. 
    99     * 
    1010     * Handles the default media experience. Automatically creates 
    … …  
    3232            frame = new MediaFrame.Post( attributes ); 
    3333        } else if ( 'manage' === attributes.frame && MediaFrame.Manage ) { 
    34             frame = new MediaFrame.Manage( attributes );  
     34            frame = new MediaFrame.Manage( attributes ); 
    3535        } else if ( 'image' === attributes.frame && MediaFrame.ImageDetails ) { 
    3636            frame = new MediaFrame.ImageDetails( attributes ); 

  • trunk/src/wp-includes/js/media-views.js

    r28682 r28688  
    9393    _.extend( media.controller.Region.prototype, { 
    9494        /** 
    95          * Switch modes 
     95         * Activate a mode. 
    9696         * 
    9797         * @param {string} mode 
    9898         * 
    99          * @fires wp.media.controller.Region#{id}:activate:{mode} 
    100          * @fires wp.media.controller.Region#{id}:deactivate:{mode} 
     99         * @fires this.view#{this.id}:activate:{this._mode} 
     100         * @fires this.view#{this.id}:activate 
     101         * @fires this.view#{this.id}:deactivate:{this._mode} 
     102         * @fires this.view#{this.id}:deactivate 
    101103         * 
    102          * @returns {wp.media.controller.Region} Returns itself to allow chaining 
     104         * @returns {wp.media.controller.Region} Returns itself to allow chaining. 
    103105         */ 
    104106        mode: function( mode ) { 
    … …  
    111113            } 
    112114 
     115            /** 
     116             * Region mode deactivation event. 
     117             * 
     118             * @event this.view#{this.id}:deactivate:{this._mode} 
     119             * @event this.view#{this.id}:deactivate 
     120             */ 
    113121            this.trigger('deactivate'); 
     122 
    114123            this._mode = mode; 
    115124            this.render( mode ); 
     125 
     126            /** 
     127             * Region mode activation event. 
     128             * 
     129             * @event this.view#{this.id}:activate:{this._mode} 
     130             * @event this.view#{this.id}:activate 
     131             */ 
    116132            this.trigger('activate'); 
    117133            return this; 
    118134        }, 
    119135        /** 
    120          * Render a new mode, the view is set in the `create` callback method 
    121          *   of the extending class 
    122          * 
    123          * If no mode is provided, just re-render the current mode. 
    124          * If the provided mode isn't active, perform a full switch. 
     136         * Render a mode. 
    125137         * 
    126138         * @param {string} mode 
    127139         * 
    128          * @fires wp.media.controller.Region#{id}:create:{mode} 
    129          * @fires wp.media.controller.Region#{id}:render:{mode} 
     140         * @fires this.view#{this.id}:create:{this._mode} 
     141         * @fires this.view#{this.id}:create 
     142         * @fires this.view#{this.id}:render:{this._mode} 
     143         * @fires this.view#{this.id}:render 
    130144         * 
    131145         * @returns {wp.media.controller.Region} Returns itself to allow chaining 
    132146         */ 
    133147        render: function( mode ) { 
     148            // If the mode isn't active, activate it. 
    134149            if ( mode && mode !== this._mode ) { 
    135150                return this.mode( mode ); 
    … …  
    139154                view; 
    140155 
     156            /** 
     157             * Create region view event. 
     158             * 
     159             * Region view creation takes place in an event callback on the frame. 
     160             * 
     161             * @event this.view#{this.id}:create:{this._mode} 
     162             * @event this.view#{this.id}:create 
     163             */ 
    141164            this.trigger( 'create', set ); 
    142165            view = set.view; 
     166 
     167            /** 
     168             * Render region view event. 
     169             * 
     170             * Region view creation takes place in an event callback on the frame. 
     171             * 
     172             * @event this.view#{this.id}:create:{this._mode} 
     173             * @event this.view#{this.id}:create 
     174             */ 
    143175            this.trigger( 'render', view ); 
    144176            if ( view ) { 
    … …  
    149181 
    150182        /** 
    151          * @returns {wp.media.View} Returns the selector's first subview 
     183         * Get the region's view. 
     184         * 
     185         * @returns {wp.media.View} 
    152186         */ 
    153187        get: function() { 
    … …  
    156190 
    157191        /** 
     192         * Set the region's view as a subview of the frame. 
     193         * 
    158194         * @param {Array|Object} views 
    159195         * @param {Object} [options={}] 
    … …  
    168204 
    169205        /** 
    170          * Helper function to trigger view events based on {id}:{event}:{mode} 
     206         * Trigger regional view events on the frame. 
    171207         * 
    172208         * @param {string} event 
    173          * @returns {undefined|wp.media.controller.Region} Returns itself to allow chaining 
     209         * @returns {undefined|wp.media.controller.Region} Returns itself to allow chaining. 
    174210         */ 
    175211        trigger: function( event ) { 
    … …  
    183219            base = this.id + ':' + event; 
    184220 
    185             // Trigger `region:action:mode` event. 
     221            // Trigger `{this.id}:{event}:{this._mode}` event on the frame. 
    186222            args[0] = base + ':' + this._mode; 
    187223            this.view.trigger.apply( this.view, args ); 
    188224 
    189             // Trigger `region:action` event. 
     225            // Trigger `{this.id}:{event}` event on the frame. 
    190226            args[0] = base; 
    191227            this.view.trigger.apply( this.view, args ); 
    … …  
    211247    media.controller.StateMachine.extend = Backbone.Model.extend; 
    212248 
    213     // Add events to the `StateMachine`. 
    214249    _.extend( media.controller.StateMachine.prototype, Backbone.Events, { 
    215250        /** 
    … …  
    287322    }); 
    288323 
    289     // Map methods from the `states` collection to the `StateMachine` itself. 
     324    // Map all event binding and triggering on a StateMachine to its `states` collection. 
    290325    _.each([ 'on', 'off', 'trigger' ], function( method ) { 
    291326        /** 
    292          * @returns {wp.media.controller.StateMachine} Returns itself to allow chaining 
     327         * @returns {wp.media.controller.StateMachine} Returns itself to allow chaining. 
    293328         */ 
    294329        media.controller.StateMachine.prototype[ method ] = function() { 
    … …  
    305340     * wp.media.controller.State 
    306341     * 
    307      * A state is a step in a workflow that when set will trigger 
    308      * the controllers for the regions to be updated as specified. This 
    309      * class is the base class that the various states used in the media 
    310      * modals extend. 
     342     * A state is a step in a workflow that when set will trigger the controllers 
     343     * for the regions to be updated as specified in the frame. This is the base 
     344     * class that the various states used in wp.media extend. 
    311345     * 
    312346     * @constructor 
    … …  
    539573 
    540574    /** 
    541      * wp.media.controller.Library 
     575     * A state for choosing an attachment from the media library. 
    542576     * 
    543577     * @constructor 
    … …  
    748782 
    749783    /** 
    750      * wp.media.controller.ImageDetails 
     784     * A state for editing the settings of an image within a content editor. 
    751785     * 
    752786     * @constructor 
    … …  
    779813 
    780814    /** 
    781      * wp.media.controller.GalleryEdit 
     815     * A state for editing a gallery's images and settings. 
    782816     * 
    783817     * @constructor 
    … …  
    878912 
    879913    /** 
    880      * wp.media.controller.GalleryAdd 
     914     * A state for adding an image to a gallery. 
    881915     * 
    882916     * @constructor 
    … …  
    11121146 
    11131147    /** 
    1114      * wp.media.controller.FeaturedImage 
     1148     * A state for selecting a featured image for a post. 
    11151149     * 
    11161150     * @constructor 
    … …  
    11951229 
    11961230    /** 
    1197      * wp.media.controller.ReplaceImage 
    1198      * 
    1199      * Replace a selected single image 
     1231     * A state for replacing an image. 
    12001232     * 
    12011233     * @constructor 
    … …  
    12671299 
    12681300    /** 
    1269      * wp.media.controller.EditImage 
     1301     * A state for editing (cropping, etc.) an image. 
    12701302     * 
    12711303     * @constructor 
    … …  
    45314563     */ 
    45324564    media.view.RouterItem = media.view.MenuItem.extend({ 
     4565        /** 
     4566         * On click handler to activate the content region's corresponding mode. 
     4567         */ 
    45334568        click: function() { 
    45344569            var contentMode = this.options.contentMode; 
Note: See TracChangeset for help on using the changeset viewer.