WordPress.org
Get WordPress

Make WordPress Core

Ticket #35465: 35465.1.diff

File 35465.1.diff, 11.3 KB (added by gma992, 7 years ago)

Converted some more docblocks and added selector and views params

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

     
    44        // Create the WordPress Backbone namespace.
    55        wp.Backbone = {};
    66
    7 
    8         // wp.Backbone.Subviews
    9         // --------------------
    10         //
    11         // A subview manager.
     7        /**
     8         * A subview manager.
     9         *
     10         * @class
     11         *
     12         * @param  {wp.Backbone.View} view  The main view.
     13         * @param  {array|object}     views The subviews for the main view.
     14         */
    1215        wp.Backbone.Subviews = function( view, views ) {
    1316                this.view = view;
    1417                this._views = _.isArray( views ) ? { '': views } : views || {};
    … …  
    1720        wp.Backbone.Subviews.extend = Backbone.Model.extend;
    1821
    1922        _.extend( wp.Backbone.Subviews.prototype, {
    20                 // ### Fetch all of the subviews
    21                 //
    22                 // Returns an array of all subviews.
     23                /**
     24                 * Fetch all of the subviews.
     25                 *
     26                 * @return {array} All the subviews.
     27                 */
    2328                all: function() {
    2429                        return _.flatten( _.values( this._views ) );
    2530                },
    2631
    27                 // ### Get a selector's subviews
    28                 //
    29                 // Fetches all subviews that match a given `selector`.
    30                 //
    31                 // If no `selector` is provided, it will grab all subviews attached
    32                 // to the view's root.
     32                /**
     33                 * Fetches all subviews that match a given `selector`.
     34                 *
     35                 * If no `selector` is provided, it will grab all subviews attached
     36                 * to the view's root.
     37                 *
     38                 * @param {string} selector A jQuery selector.
     39                 *
     40                 * @return {array}
     41                 */
    3342                get: function( selector ) {
    3443                        selector = selector || '';
    3544                        return this._views[ selector ];
    3645                },
    3746
    38                 // ### Get a selector's first subview
    39                 //
    40                 // Fetches the first subview that matches a given `selector`.
    41                 //
    42                 // If no `selector` is provided, it will grab the first subview
    43                 // attached to the view's root.
    44                 //
    45                 // Useful when a selector only has one subview at a time.
     47                /**
     48                 * Fetches the first subview that matches a given `selector`.
     49                 *
     50                 * If no `selector` is provided, it will grab the first subview
     51                 * attached to the view's root.
     52                 *
     53                 * Useful when a selector only has one subview at a time.
     54                 *
     55                 * @param {string} selector A jQuery selector.
     56                 *
     57                 * @return {Backbone.View} The view.
     58                 */
    4659                first: function( selector ) {
    4760                        var views = this.get( selector );
    4861                        return views && views.length ? views[0] : null;
    4962                },
    50 
    51                 // ### Register subview(s)
    52                 //
    53                 // Registers any number of `views` to a `selector`.
    54                 //
    55                 // When no `selector` is provided, the root selector (the empty string)
    56                 // is used. `views` accepts a `Backbone.View` instance or an array of
    57                 // `Backbone.View` instances.
    58                 //
    59                 // ---
    60                 //
    61                 // Accepts an `options` object, which has a significant effect on the
    62                 // resulting behavior.
    63                 //
    64                 // `options.silent` – *boolean, `false`*
    65                 // > If `options.silent` is true, no DOM modifications will be made.
    66                 //
    67                 // `options.add` – *boolean, `false`*
    68                 // > Use `Views.add()` as a shortcut for setting `options.add` to true.
    69                 //
    70                 // > By default, the provided `views` will replace
    71                 // any existing views associated with the selector. If `options.add`
    72                 // is true, the provided `views` will be added to the existing views.
    73                 //
    74                 // `options.at` – *integer, `undefined`*
    75                 // > When adding, to insert `views` at a specific index, use
    76                 // `options.at`. By default, `views` are added to the end of the array.
     63                /**
     64                * Register subview(s)
     65                *
     66                * Registers any number of `views` to a `selector`.
     67                *
     68                * When no `selector` is provided, the root selector (the empty string)
     69                * is used. `views` accepts a `Backbone.View` instance or an array of
     70                * `Backbone.View` instances.
     71                *
     72                * ---
     73                *
     74                * Accepts an `options` object, which has a significant effect on the
     75                * resulting behavior.
     76                *
     77                * `options.silent` – *boolean, `false`*
     78                * > If `options.silent` is true, no DOM modifications will be made.
     79                *
     80                * `options.add` – *boolean, `false`*
     81                * > Use `Views.add()` as a shortcut for setting `options.add` to true.
     82                *
     83                * > By default, the provided `views` will replace
     84                * any existing views associated with the selector. If `options.add`
     85                * is true, the provided `views` will be added to the existing views.
     86                *
     87                * `options.at` – *integer, `undefined`*
     88                * > When adding, to insert `views` at a specific index, use
     89                * `options.at`. By default, `views` are added to the end of the array.
     90                *
     91                * @param {string}                       selector        A jQuery selector.
     92                * @param  {array|object}        views           The subviews for the main view.
     93                * @param {} options
     94                *
     95                * @return
     96                */
    7797                set: function( selector, views, options ) {
    7898                        var existing, next;
    7999
    … …  
    128148
    129149                        return this;
    130150                },
    131 
    132                 // ### Add subview(s) to existing subviews
    133                 //
    134                 // An alias to `Views.set()`, which defaults `options.add` to true.
    135                 //
    136                 // Adds any number of `views` to a `selector`.
    137                 //
    138                 // When no `selector` is provided, the root selector (the empty string)
    139                 // is used. `views` accepts a `Backbone.View` instance or an array of
    140                 // `Backbone.View` instances.
    141                 //
    142                 // Use `Views.set()` when setting `options.add` to `false`.
    143                 //
    144                 // Accepts an `options` object. By default, provided `views` will be
    145                 // inserted at the end of the array of existing views. To insert
    146                 // `views` at a specific index, use `options.at`. If `options.silent`
    147                 // is true, no DOM modifications will be made.
    148                 //
    149                 // For more information on the `options` object, see `Views.set()`.
     151                /**
     152                * Add subview(s) to existing subviews
     153                *
     154                * An alias to `Views.set()`, which defaults `options.add` to true.
     155                *
     156                * Adds any number of `views` to a `selector`.
     157                *
     158                * When no `selector` is provided, the root selector (the empty string)
     159                * is used. `views` accepts a `Backbone.View` instance or an array of
     160                * `Backbone.View` instances.
     161                *
     162                * Use `Views.set()` when setting `options.add` to `false`.
     163                *
     164                * Accepts an `options` object. By default, provided `views` will be
     165                * inserted at the end of the array of existing views. To insert
     166                * `views` at a specific index, use `options.at`. If `options.silent`
     167                * is true, no DOM modifications will be made.
     168                *
     169                * For more information on the `options` object, see `Views.set()`.
     170                *
     171                * @param {string}                       selector A jQuery selector.
     172                * @param  {array|object}        views The subviews for the main view.
     173                * @param {} options
     174                *
     175                * @return
     176                */
    150177                add: function( selector, views, options ) {
    151178                        if ( ! _.isString( selector ) ) {
    152179                                options  = views;
    … …  
    156183
    157184                        return this.set( selector, views, _.extend({ add: true }, options ) );
    158185                },
    159 
    160                 // ### Stop tracking subviews
    161                 //
    162                 // Stops tracking `views` registered to a `selector`. If no `views` are
    163                 // set, then all of the `selector`'s subviews will be unregistered and
    164                 // removed.
    165                 //
    166                 // Accepts an `options` object. If `options.silent` is set, `remove`
    167                 // will *not* be triggered on the unregistered views.
     186                /**
     187                * Stop tracking subviews
     188                *
     189                * Stops tracking `views` registered to a `selector`. If no `views` are
     190                * set, then all of the `selector`'s subviews will be unregistered and
     191                * removed.
     192                *
     193                * Accepts an `options` object. If `options.silent` is set, `remove`
     194                * will *not* be triggered on the unregistered views.
     195                *
     196                * @param {string}                       selector A jQuery selector.
     197                * @param  {array|object}        views The subviews for the main view.
     198                * @param {} options
     199                *
     200                * @return
     201                */
    168202                unset: function( selector, views, options ) {
    169203                        var existing;
    170204
    … …  
    197231                        $( _.pluck( this.all(), 'el' ) ).detach();
    198232                        return this;
    199233                },
    200 
    201                 // ### Render all subviews
    202                 //
    203                 // Renders all subviews. Used in conjunction with `Views.detach()`.
     234                /**
     235                * Render all subviews
     236                *
     237                * Renders all subviews. Used in conjunction with `Views.detach()`.
     238                *
     239                * @param {array|object}         views           The subviews for the main view.
     240                * @param {string}                       selector        A jQuery selector.
     241                *
     242                * @return {array}
     243                */
    204244                render: function() {
    205245                        var options = {
    206246                                        ready: this._isReady()
    … …  
    213253                        this.rendered = true;
    214254                        return this;
    215255                },
    216 
    217                 // ### Remove all subviews
    218                 //
    219                 // Triggers the `remove()` method on all subviews. Detaches the master
    220                 // view from its parent. Resets the internals of the views manager.
    221                 //
    222                 // Accepts an `options` object. If `options.silent` is set, `unset`
    223                 // will *not* be triggered on the master view's parent.
     256                /**
     257                * Remove all subviews
     258                *
     259                * Triggers the `remove()` method on all subviews. Detaches the master
     260                * view from its parent. Resets the internals of the views manager.
     261                *
     262                * Accepts an `options` object. If `options.silent` is set, `unset`
     263                * will *not* be triggered on the master view's parent.
     264                *
     265                * @param {} options
     266                *
     267                * @return {}
     268                */
    224269                remove: function( options ) {
    225270                        if ( ! options || ! options.silent ) {
    226271                                if ( this.parent && this.parent.views )
    … …  
    233278                        this._views = [];
    234279                        return this;
    235280                },
    236 
    237                 // ### Replace a selector's subviews
    238                 //
    239                 // By default, sets the `$target` selector's html to the subview `els`.
    240                 //
    241                 // Can be overridden in subclasses.
     281                /**
     282                * Replace a selector's subviews
     283                *
     284                * By default, sets the `$target` selector's html to the subview `els`.
     285                *
     286                * Can be overridden in subclasses.
     287                *
     288                * @param {} target
     289                * @param {} els
     290                *
     291                * @return
     292                */
    242293                replace: function( $target, els ) {
    243294                        $target.html( els );
    244295                        return this;
    245296                },
    246 
    247                 // ### Insert subviews into a selector
    248                 //
    249                 // By default, appends the subview `els` to the end of the `$target`
    250                 // selector. If `options.at` is set, inserts the subview `els` at the
    251                 // provided index.
    252                 //
    253                 // Can be overridden in subclasses.
     297                /**
     298                * Insert subviews into a selector
     299                *
     300                * By default, appends the subview `els` to the end of the `$target`
     301                * selector. If `options.at` is set, inserts the subview `els` at the
     302                * provided index.
     303                *
     304                * Can be overridden in subclasses.
     305                *
     306                * @param {} target
     307                * @param {} els
     308                * @param {} options
     309                *
     310                * @return
     311                */
    254312                insert: function( $target, els, options ) {
    255313                        var at = options && options.at,
    256314                                $children;
    … …  
    278336                                return view.views;
    279337                        }).flatten().where({ attached: true }).invoke('ready');
    280338                },
    281 
    282                 // #### Internal. Attaches a series of views to a selector.
    283                 //
    284                 // Checks to see if a matching selector exists, renders the views,
    285                 // performs the proper DOM operation, and then checks if the view is
    286                 // attached to the document.
     339                /**
     340                * Internal. Attaches a series of views to a selector.
     341                *
     342                * Checks to see if a matching selector exists, renders the views,
     343                * performs the proper DOM operation, and then checks if the view is
     344                * attached to the document.
     345                *
     346                * @param {string}                       selector A jQuery selector.
     347                * @param  {array|object}        views The subviews for the main view.
     348                * @param {} options
     349                *
     350                * @return
     351                */
    287352                _attach: function( selector, views, options ) {
    288353                        var $selector = selector ? this.view.$( selector ) : this.view.$el,
    289354                                managers;
    … …  
    331396                }
    332397        });
    333398
    334 
    335         // wp.Backbone.View
    336         // ----------------
    337         //
    338         // The base view class.
     399        /**
     400         * The base view class.
     401         *
     402         * @class
     403         *
     404         */
    339405        wp.Backbone.View = Backbone.View.extend({
    340406                // The constructor for the `Views` manager.
    341407                Subviews: wp.Backbone.Subviews,