sergiotarxz
/
Wordpress
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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

Changes some additional docs after [42993].

Props birgire, adamsilverstein, netweb.
Fixes #35465.


git-svn-id: https://develop.svn.wordpress.org/trunk@42996 602fd350-edb4-49c9-b593-d223f7449a82
This commit is contained in:
Anton Timmermans 2018-04-22 14:36:23 +00:00
parent c9aaa0ddb7
commit db0a8af84b
1 changed files with 38 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
src/wp-includes/js/wp-backbone.js
View File

@ -20,7 +20,7 @@ window.wp = window.wp || {};
* @class * @class
* *
* @param {wp.Backbone.View} view The main view. * @param {wp.Backbone.View} view The main view.
* @param {array|Object} views The subviews for the main view. * @param {Array|Object} views The subviews for the main view.
*/ */
wp.Backbone.Subviews = function( view, views ) { wp.Backbone.Subviews = function( view, views ) {
this.view = view; this.view = view;
@ -35,7 +35,7 @@ window.wp = window.wp || {};
* *
* @since 3.5.0 * @since 3.5.0
* *
* @return {array} All the subviews. * @return {Array} All the subviews.
*/ */
all: function() { all: function() {
return _.flatten( _.values( this._views ) ); return _.flatten( _.values( this._views ) );
@ -51,7 +51,7 @@ window.wp = window.wp || {};
* *
* @param {string} selector A jQuery selector. * @param {string} selector A jQuery selector.
* *
* @return {array} * @return {Array} All the subviews that match the selector.
*/ */
get: function( selector ) { get: function( selector ) {
selector = selector || ''; selector = selector || '';
@ -91,24 +91,24 @@ window.wp = window.wp || {};
* Accepts an `options` object, which has a significant effect on the * Accepts an `options` object, which has a significant effect on the
* resulting behavior. * resulting behavior.
* *
* `options.silent` – *boolean, `false`* * `options.silent` - *boolean, `false`*
* > If `options.silent` is true, no DOM modifications will be made. * If `options.silent` is true, no DOM modifications will be made.
* *
* `options.add` – *boolean, `false`* * `options.add` - *boolean, `false`*
* > Use `Views.add()` as a shortcut for setting `options.add` to true. * Use `Views.add()` as a shortcut for setting `options.add` to true.
* *
* > By default, the provided `views` will replace * By default, the provided `views` will replace any existing views
* any existing views associated with the selector. If `options.add` * associated with the selector. If `options.add` is true, the provided
* is true, the provided `views` will be added to the existing views. * `views` will be added to the existing views.
* *
* `options.at` – *integer, `undefined`* * `options.at` - *integer, `undefined`*
* > When adding, to insert `views` at a specific index, use * When adding, to insert `views` at a specific index, use `options.at`.
* `options.at`. By default, `views` are added to the end of the array. * By default, `views` are added to the end of the array.
* *
* @since 3.5.0 * @since 3.5.0
* *
* @param {string} selector A jQuery selector. * @param {string} selector A jQuery selector.
* @param {array|Object} views The subviews for the main view. * @param {Array|Object} views The subviews for the main view.
* @param {Object} options Options for call. If `options.silent` is true, * @param {Object} options Options for call. If `options.silent` is true,
* no DOM modifications will be made. Use * no DOM modifications will be made. Use
* `Views.add()` as a shortcut for setting * `Views.add()` as a shortcut for setting
@ -117,7 +117,7 @@ window.wp = window.wp || {};
* the existing views. When adding, to insert * the existing views. When adding, to insert
* `views` at a specific index, use `options.at`. * `views` at a specific index, use `options.at`.
* *
* @return wp.Backbone.Subviews * @return {wp.Backbone.Subviews} The current Subviews instance.
*/ */
set: function( selector, views, options ) { set: function( selector, views, options ) {
var existing, next; var existing, next;
@ -197,13 +197,13 @@ window.wp = window.wp || {};
* @since 3.5.0 * @since 3.5.0
* *
* @param {string} selector A jQuery selector. * @param {string} selector A jQuery selector.
* @param {array|object} views The subviews for the main view. * @param {Array|Object} views The subviews for the main view.
* @param {Object} options Options for call. To insert `views` at a * @param {Object} options Options for call. To insert `views` at a
* specific index, use `options.at`. If * specific index, use `options.at`. If
* `options.silent` is true, no DOM modifications * `options.silent` is true, no DOM modifications
* will be made. * will be made.
* *
* @return wp.Backbone.Subviews * @return {wp.Backbone.Subviews} The current subviews instance.
*/ */
add: function( selector, views, options ) { add: function( selector, views, options ) {
if ( ! _.isString( selector ) ) { if ( ! _.isString( selector ) ) {
@ -228,7 +228,7 @@ window.wp = window.wp || {};
* @since 3.5.0 * @since 3.5.0
* *
* @param {string} selector A jQuery selector. * @param {string} selector A jQuery selector.
* @param {array|object} views The subviews for the main view. * @param {Array|Object} views The subviews for the main view.
* @param {Object} options Options for call. If `options.silent` is set, * @param {Object} options Options for call. If `options.silent` is set,
* `remove` will *not* be triggered on the * `remove` will *not* be triggered on the
* unregistered views. * unregistered views.
@ -273,7 +273,7 @@ window.wp = window.wp || {};
}, },
/** /**
* Renders all subviews * Renders all subviews.
* *
* Used in conjunction with `Views.detach()`. * Used in conjunction with `Views.detach()`.
* *
@ -295,7 +295,7 @@ window.wp = window.wp || {};
}, },
/** /**
* Removes all subviews * Removes all subviews.
* *
* Triggers the `remove()` method on all subviews. Detaches the master * Triggers the `remove()` method on all subviews. Detaches the master
* view from its parent. Resets the internals of the views manager. * view from its parent. Resets the internals of the views manager.
@ -344,7 +344,7 @@ window.wp = window.wp || {};
}, },
/** /**
* Insert subviews into a selector * Insert subviews into a selector.
* *
* By default, appends the subview `els` to the end of the `$target` * By default, appends the subview `els` to the end of the `$target`
* selector. If `options.at` is set, inserts the subview `els` at the * selector. If `options.at` is set, inserts the subview `els` at the
@ -404,10 +404,10 @@ window.wp = window.wp || {};
* *
* @private * @private
* *
* @param {string} selector A jQuery selector. * @param {string} selector A jQuery selector.
* @param {array|object} views The subviews for the main view. * @param {Array|Object} views The subviews for the main view.
* @param {Object} options Options for call. * @param {Object} options Options for call.
* @param {boolean} options.add If true the provided views will be added. * @param {boolean} options.add If true the provided views will be added.
* *
* @return {wp.Backbone.Subviews} The current Subviews instance. * @return {wp.Backbone.Subviews} The current Subviews instance.
*/ */
@ -433,8 +433,10 @@ window.wp = window.wp || {};
// Insert or replace the views. // Insert or replace the views.
this[ options.add ? 'insert' : 'replace' ]( $selector, _.pluck( views, 'el' ), options ); this[ options.add ? 'insert' : 'replace' ]( $selector, _.pluck( views, 'el' ), options );
// Set attached and trigger ready if the current view is already /*
// attached to the DOM. * Set attached and trigger ready if the current view is already
* attached to the DOM.
*/
_.each( managers, function( manager ) { _.each( managers, function( manager ) {
manager.attached = true; manager.attached = true;
@ -452,7 +454,7 @@ window.wp = window.wp || {};
* *
* @private * @private
* *
* @returns {boolean} Whether or not the current view is in the DOM. * @return {boolean} Whether or not the current view is in the DOM.
*/ */
_isReady: function() { _isReady: function() {
var node = this.view.el; var node = this.view.el;
@ -480,11 +482,12 @@ window.wp = window.wp || {};
* @since 3.5.0 * @since 3.5.0
* @since 3.6.0 Moved wp.media.View to wp.Backbone.View * @since 3.6.0 Moved wp.media.View to wp.Backbone.View
* *
* @memberOf wp.Backbone
*
* @constructs * @constructs
* @augments Backbone.View * @augments Backbone.View
* *
* @memberOf wp.Backbone
*
*
* @param {Object} options The options for this view. * @param {Object} options The options for this view.
*/ */
constructor: function( options ) { constructor: function( options ) {
@ -497,9 +500,11 @@ window.wp = window.wp || {};
}, },
/** /**
* Removes this view and all subviews.
*
* @since 3.5.0 * @since 3.5.0
* *
* Removes this view and all subviews. * @return {wp.Backbone.Subviews} The current Subviews instance.
*/ */
remove: function() { remove: function() {
var result = Backbone.View.prototype.remove.apply( this, arguments ); var result = Backbone.View.prototype.remove.apply( this, arguments );
@ -516,7 +521,7 @@ window.wp = window.wp || {};
* *
* @since 3.5.0 * @since 3.5.0
* *
* @returns {wp.Backbone.View} The current instance of the view. * @return {wp.Backbone.View} The current instance of the view.
*/ */
render: function() { render: function() {
var options; var options;
@ -541,7 +546,7 @@ window.wp = window.wp || {};
* *
* @since 3.5.0 * @since 3.5.0
* *
* @returns {Object} The options for this view. * @return {Object} The options for this view.
*/ */
prepare: function() { prepare: function() {
return this.options; return this.options;