WordPress.org
Get WordPress

Make WordPress Core

Changeset 42993


Ignore:
Timestamp:
04/19/2018 02:01:48 PM (6 years ago)
Author:
atimmer
Message:

Docs: Improve JSDoc for wp-includes/js/wp-backbone.js.

Props ericlewis, gma992, adamsilverstein.
Fixes #35465.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/js/wp-backbone.js

    r41351 r42993  
    1010    wp.Backbone = {};
    1111
    12 
    13     // wp.Backbone.Subviews
    14     // --------------------
    15     //
    16     // A subview manager.
     12    /**
     13     * A backbone subview manager.
     14     *
     15     * @since 3.5.0
     16     * @since 3.6.0 Moved wp.media.Views to wp.Backbone.Subviews.
     17     *
     18     * @memberOf wp.Backbone
     19     *
     20     * @class
     21     *
     22     * @param  {wp.Backbone.View} view  The main view.
     23     * @param  {array|Object}     views The subviews for the main view.
     24     */
    1725    wp.Backbone.Subviews = function( view, views ) {
    1826        this.view = view;
    … …  
    2331
    2432    _.extend( wp.Backbone.Subviews.prototype, {
    25         // ### Fetch all of the subviews
    26         //
    27         // Returns an array of all subviews.
     33        /**
     34         * Fetches all of the subviews.
     35         *
     36         * @since 3.5.0
     37         *
     38         * @return {array} All the subviews.
     39         */
    2840        all: function() {
    29             return _.flatten( _.values( this._views ) );
    30         },
    31 
    32         // ### Get a selector's subviews
    33         //
    34         // Fetches all subviews that match a given `selector`.
    35         //
    36         // If no `selector` is provided, it will grab all subviews attached
    37         // to the view's root.
     41            return _.flatten( _.values( this._views ) );
     42        },
     43
     44        /**
     45         * Fetches all subviews that match a given `selector`.
     46         *
     47         * If no `selector` is provided, it will grab all subviews attached
     48         * to the view's root.
     49         *
     50         * @since 3.5.0
     51         *
     52         * @param {string} selector A jQuery selector.
     53         *
     54         * @return {array}
     55         */
    3856        get: function( selector ) {
    3957            selector = selector || '';
    … …  
    4159        },
    4260
    43         // ### Get a selector's first subview
    44         //
    45         // Fetches the first subview that matches a given `selector`.
    46         //
    47         // If no `selector` is provided, it will grab the first subview
    48         // attached to the view's root.
    49         //
    50         // Useful when a selector only has one subview at a time.
     61        /**
     62         * Fetches the first subview that matches a given `selector`.
     63         *
     64         * If no `selector` is provided, it will grab the first subview attached to the
     65         * view's root.
     66         *
     67         * Useful when a selector only has one subview at a time.
     68         *
     69         * @since 3.5.0
     70         *
     71         * @param {string} selector A jQuery selector.
     72         *
     73         * @return {Backbone.View} The view.
     74         */
    5175        first: function( selector ) {
    5276            var views = this.get( selector );
    … …  
    5478        },
    5579
    56         // ### Register subview(s)
    57         //
    58         // Registers any number of `views` to a `selector`.
    59         //
    60         // When no `selector` is provided, the root selector (the empty string)
    61         // is used. `views` accepts a `Backbone.View` instance or an array of
    62         // `Backbone.View` instances.
    63         //
    64         // ---
    65         //
    66         // Accepts an `options` object, which has a significant effect on the
    67         // resulting behavior.
    68         //
    69         // `options.silent` – *boolean, `false`*
    70         // > If `options.silent` is true, no DOM modifications will be made.
    71         //
    72         // `options.add` – *boolean, `false`*
    73         // > Use `Views.add()` as a shortcut for setting `options.add` to true.
    74         //
    75         // > By default, the provided `views` will replace
    76         // any existing views associated with the selector. If `options.add`
    77         // is true, the provided `views` will be added to the existing views.
    78         //
    79         // `options.at` – *integer, `undefined`*
    80         // > When adding, to insert `views` at a specific index, use
    81         // `options.at`. By default, `views` are added to the end of the array.
     80        /**
     81         * Registers subview(s).
     82         *
     83         * Registers any number of `views` to a `selector`.
     84         *
     85         * When no `selector` is provided, the root selector (the empty string)
     86         * is used. `views` accepts a `Backbone.View` instance or an array of
     87         * `Backbone.View` instances.
     88         *
     89         * ---
     90         *
     91         * Accepts an `options` object, which has a significant effect on the
     92         * resulting behavior.
     93         *
     94         * `options.silent` – *boolean, `false`*
     95         * > If `options.silent` is true, no DOM modifications will be made.
     96         *
     97         * `options.add` – *boolean, `false`*
     98         * > Use `Views.add()` as a shortcut for setting `options.add` to true.
     99         *
     100         * > By default, the provided `views` will replace
     101         * any existing views associated with the selector. If `options.add`
     102         * is true, the provided `views` will be added to the existing views.
     103         *
     104         * `options.at` – *integer, `undefined`*
     105         * > When adding, to insert `views` at a specific index, use
     106         * `options.at`. By default, `views` are added to the end of the array.
     107         *
     108         * @since 3.5.0
     109         *
     110         * @param {string}       selector A jQuery selector.
     111         * @param {array|Object} views    The subviews for the main view.
     112         * @param {Object}       options  Options for call. If `options.silent` is true,
     113         *                                no DOM  modifications will be made. Use
     114         *                                `Views.add()` as a shortcut for setting
     115         *                                `options.add` to true. If `options.add` is
     116         *                                true, the provided `views` will be added to
     117         *                                the existing views. When adding, to insert
     118         *                                `views` at a specific index, use `options.at`.
     119         *
     120         * @return wp.Backbone.Subviews
     121         */
    82122        set: function( selector, views, options ) {
    83123            var existing, next;
    … …  
    135175        },
    136176
    137         // ### Add subview(s) to existing subviews
    138         //
    139         // An alias to `Views.set()`, which defaults `options.add` to true.
    140         //
    141         // Adds any number of `views` to a `selector`.
    142         //
    143         // When no `selector` is provided, the root selector (the empty string)
    144         // is used. `views` accepts a `Backbone.View` instance or an array of
    145         // `Backbone.View` instances.
    146         //
    147         // Use `Views.set()` when setting `options.add` to `false`.
    148         //
    149         // Accepts an `options` object. By default, provided `views` will be
    150         // inserted at the end of the array of existing views. To insert
    151         // `views` at a specific index, use `options.at`. If `options.silent`
    152         // is true, no DOM modifications will be made.
    153         //
    154         // For more information on the `options` object, see `Views.set()`.
     177        /**
     178         * Add subview(s) to existing subviews.
     179         *
     180         * An alias to `Views.set()`, which defaults `options.add` to true.
     181         *
     182         * Adds any number of `views` to a `selector`.
     183         *
     184         * When no `selector` is provided, the root selector (the empty string)
     185         * is used. `views` accepts a `Backbone.View` instance or an array of
     186         * `Backbone.View` instances.
     187         *
     188         * Uses `Views.set()` when setting `options.add` to `false`.
     189         *
     190         * Accepts an `options` object. By default, provided `views` will be
     191         * inserted at the end of the array of existing views. To insert
     192         * `views` at a specific index, use `options.at`. If `options.silent`
     193         * is true, no DOM modifications will be made.
     194         *
     195         * For more information on the `options` object, see `Views.set()`.
     196         *
     197         * @since 3.5.0
     198         *
     199         * @param {string}       selector A jQuery selector.
     200         * @param {array|object} views    The subviews for the main view.
     201         * @param {Object}       options  Options for call.  To insert `views` at a
     202         *                                specific index, use `options.at`. If
     203         *                                `options.silent` is true, no DOM modifications
     204         *                                will be made.
     205         *
     206         * @return wp.Backbone.Subviews
     207         */
    155208        add: function( selector, views, options ) {
    156209            if ( ! _.isString( selector ) ) {
    … …  
    163216        },
    164217
    165         // ### Stop tracking subviews
    166         //
    167         // Stops tracking `views` registered to a `selector`. If no `views` are
    168         // set, then all of the `selector`'s subviews will be unregistered and
    169         // removed.
    170         //
    171         // Accepts an `options` object. If `options.silent` is set, `remove`
    172         // will *not* be triggered on the unregistered views.
     218        /**
     219         * Removes an added subview.
     220         *
     221         * Stops tracking `views` registered to a `selector`. If no `views` are
     222         * set, then all of the `selector`'s subviews will be unregistered and
     223         * removed.
     224         *
     225         * Accepts an `options` object. If `options.silent` is set, `remove`
     226         * will *not* be triggered on the unregistered views.
     227         *
     228         * @since 3.5.0
     229         *
     230         * @param {string}       selector A jQuery selector.
     231         * @param {array|object} views    The subviews for the main view.
     232         * @param {Object}       options  Options for call. If `options.silent` is set,
     233         *                                `remove` will *not* be triggered on the
     234         *                                unregistered views.
     235         *
     236         * @return {wp.Backbone.Subviews} The current Subviews instance.
     237         */
    173238        unset: function( selector, views, options ) {
    174239            var existing;
    … …  
    193258        },
    194259
    195         // ### Detach all subviews
    196         //
    197         // Detaches all subviews from the DOM.
    198         //
    199         // Helps to preserve all subview events when re-rendering the master
    200         // view. Used in conjunction with `Views.render()`.
     260        /**
     261         * Detaches all subviews.
     262         *
     263         * Helps to preserve all subview events when re-rendering the master
     264         * view. Used in conjunction with `Views.render()`.
     265         *
     266         * @since 3.5.0
     267         *
     268         * @return {wp.Backbone.Subviews} The current Subviews instance.
     269         */
    201270        detach: function() {
    202271            $( _.pluck( this.all(), 'el' ) ).detach();
    … …  
    204273        },
    205274
    206         // ### Render all subviews
    207         //
    208         // Renders all subviews. Used in conjunction with `Views.detach()`.
     275        /**
     276         * Renders all subviews
     277         *
     278         * Used in conjunction with `Views.detach()`.
     279         *
     280         * @since 3.5.0
     281         *
     282         * @return {wp.Backbone.Subviews} The current Subviews instance.
     283        */
    209284        render: function() {
    210285            var options = {
    … …  
    220295        },
    221296
    222         // ### Remove all subviews
    223         //
    224         // Triggers the `remove()` method on all subviews. Detaches the master
    225         // view from its parent. Resets the internals of the views manager.
    226         //
    227         // Accepts an `options` object. If `options.silent` is set, `unset`
    228         // will *not* be triggered on the master view's parent.
     297        /**
     298         * Removes all subviews
     299         *
     300         * Triggers the `remove()` method on all subviews. Detaches the master
     301         * view from its parent. Resets the internals of the views manager.
     302         *
     303         * Accepts an `options` object. If `options.silent` is set, `unset`
     304         * will *not* be triggered on the master view's parent.
     305         *
     306         * @since 3.6.0
     307         *
     308         * @param {Object}  options        Options for call.
     309         * @param {boolean} options.silent If true, `unset` wil *not* be triggered on
     310         *                                 the master views' parent.
     311         *
     312         * @return {wp.Backbone.Subviews} The current Subviews instance.
     313        */
    229314        remove: function( options ) {
    230315            if ( ! options || ! options.silent ) {
    … …  
    240325        },
    241326
    242         // ### Replace a selector's subviews
    243         //
    244         // By default, sets the `$target` selector's html to the subview `els`.
    245         //
    246         // Can be overridden in subclasses.
     327        /**
     328         * Replaces a selector's subviews
     329         *
     330         * By default, sets the `$target` selector's html to the subview `els`.
     331         *
     332         * Can be overridden in subclasses.
     333         *
     334         * @since 3.5.0
     335         *
     336         * @param {string} $target Selector where to put the elements.
     337         * @param {*} els HTML or elements to put into the selector's HTML.
     338         *
     339         * @return {wp.Backbone.Subviews} The current Subviews instance.
     340         */
    247341        replace: function( $target, els ) {
    248342            $target.html( els );
    … …  
    250344        },
    251345
    252         // ### Insert subviews into a selector
    253         //
    254         // By default, appends the subview `els` to the end of the `$target`
    255         // selector. If `options.at` is set, inserts the subview `els` at the
    256         // provided index.
    257         //
    258         // Can be overridden in subclasses.
     346        /**
     347         * Insert subviews into a selector
     348         *
     349         * By default, appends the subview `els` to the end of the `$target`
     350         * selector. If `options.at` is set, inserts the subview `els` at the
     351         * provided index.
     352         *
     353         * Can be overridden in subclasses.
     354         *
     355         * @since 3.5.0
     356         *
     357         * @param {string}  $target    Selector where to put the elements.
     358         * @param {*}       els        HTML or elements to put at the end of the
     359         *                             $target.
     360         * @param {?Object} options    Options for call.
     361         * @param {?number} options.at At which index to put the elements.
     362         *
     363         * @return {wp.Backbone.Subviews} The current Subviews instance.
     364         */
    259365        insert: function( $target, els, options ) {
    260366            var at = options && options.at,
    … …  
    269375        },
    270376
    271         // ### Trigger the ready event
    272         //
    273         // **Only use this method if you know what you're doing.**
    274         // For performance reasons, this method does not check if the view is
    275         // actually attached to the DOM. It's taking your word for it.
    276         //
    277         // Fires the ready event on the current view and all attached subviews.
     377        /**
     378         * Triggers the ready event.
     379         *
     380         * Only use this method if you know what you're doing. For performance reasons,
     381         * this method does not check if the view is actually attached to the DOM. It's
     382         * taking your word for it.
     383         *
     384         * Fires the ready event on the current view and all attached subviews.
     385         *
     386         * @since 3.5.0
     387         */
    278388        ready: function() {
    279389            this.view.trigger('ready');
    … …  
    284394            }).flatten().where({ attached: true }).invoke('ready');
    285395        },
    286 
    287         // #### Internal. Attaches a series of views to a selector.
    288         //
    289         // Checks to see if a matching selector exists, renders the views,
    290         // performs the proper DOM operation, and then checks if the view is
    291         // attached to the document.
     396        /**
     397         * Attaches a series of views to a selector. Internal.
     398         *
     399         * Checks to see if a matching selector exists, renders the views,
     400         * performs the proper DOM operation, and then checks if the view is
     401         * attached to the document.
     402         *
     403         * @since 3.5.0
     404         *
     405         * @private
     406         *
     407         * @param {string}       selector A jQuery selector.
     408         * @param {array|object} views    The subviews for the main view.
     409         * @param {Object}       options  Options for call.
     410         * @param {boolean}      options.add  If true the provided views will be added.
     411         *
     412         * @return {wp.Backbone.Subviews} The current Subviews instance.
     413         */
    292414        _attach: function( selector, views, options ) {
    293415            var $selector = selector ? this.view.$( selector ) : this.view.$el,
    … …  
    324446        },
    325447
    326         // #### Internal. Checks if the current view is in the DOM.
     448        /**
     449         * Determines whether or not the current view is in the DOM.
     450         *
     451         * @since 3.5.0
     452         *
     453         * @private
     454         *
     455         * @returns {boolean} Whether or not the current view is in the DOM.
     456         */
    327457        _isReady: function() {
    328458            var node = this.view.el;
    … …  
    337467    });
    338468
    339 
    340     // wp.Backbone.View
    341     // ----------------
    342     //
    343     // The base view class.
    344469    wp.Backbone.View = Backbone.View.extend({
     470
    345471        // The constructor for the `Views` manager.
    346472        Subviews: wp.Backbone.Subviews,
    347473
     474        /**
     475         * The base view class.
     476         *
     477         * This extends the backbone view to have a build-in way to use subviews. This
     478         * makes it easier to have nested views.
     479         *
     480         * @since 3.5.0
     481         * @since 3.6.0 Moved wp.media.View to wp.Backbone.View
     482         *
     483         * @memberOf wp.Backbone
     484         *
     485         * @constructs
     486         * @augments Backbone.View
     487         *
     488         * @param {Object} options The options for this view.
     489         */
    348490        constructor: function( options ) {
    349491            this.views = new this.Subviews( this, this.views );
    … …  
    355497        },
    356498
     499        /**
     500         * @since 3.5.0
     501         *
     502         * Removes this view and all subviews.
     503         */
    357504        remove: function() {
    358505            var result = Backbone.View.prototype.remove.apply( this, arguments );
    … …  
    365512        },
    366513
     514        /**
     515         * Renders this view and all subviews.
     516         *
     517         * @since 3.5.0
     518         *
     519         * @returns {wp.Backbone.View} The current instance of the view.
     520         */
    367521        render: function() {
    368522            var options;
    … …  
    383537        },
    384538
     539        /**
     540         * Returns the options for this view.
     541         *
     542         * @since 3.5.0
     543         *
     544         * @returns {Object} The options for this view.
     545         */
    385546        prepare: function() {
    386547            return this.options;
    387548        },
    388549
     550        /**
     551         * Method that is called when the ready event is triggered.
     552         *
     553         * @since 3.5.0
     554         */
    389555        ready: function() {}
    390556    });
Note: See TracChangeset for help on using the changeset viewer.