From a386be33d5f87b844d8a1c9c39aa7b461b046523 Mon Sep 17 00:00:00 2001 From: Scott Taylor Date: Sat, 25 Jan 2014 07:38:12 +0000 Subject: [PATCH] Add some JSDoc annotations to `media-models.js` to disambiguate instance properties and static class properties/methods in the base media Models. See #26870. git-svn-id: https://develop.svn.wordpress.org/trunk@27031 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/js/media-models.js | 69 ++++++++++++++++++++++++------ 1 file changed, 57 insertions(+), 12 deletions(-) diff --git a/src/wp-includes/js/media-models.js b/src/wp-includes/js/media-models.js index 569beecd41..1c65ea4f80 100644 --- a/src/wp-includes/js/media-models.js +++ b/src/wp-includes/js/media-models.js @@ -77,6 +77,8 @@ window.wp = window.wp || {}; * * Fetches a template by id. * See wp.template() in `wp-includes/js/wp-util.js`. + * + * @borrows wp.template as template */ template: wp.template, @@ -85,6 +87,8 @@ window.wp = window.wp || {}; * * Sends a POST request to WordPress. * See wp.ajax.post() in `wp-includes/js/wp-util.js`. + * + * @borrows wp.ajax.post as post */ post: wp.ajax.post, @@ -93,6 +97,8 @@ window.wp = window.wp || {}; * * Sends an XHR request to WordPress. * See wp.ajax.send() in `wp-includes/js/wp-util.js`. + * + * @borrows wp.ajax.send as ajax */ ajax: wp.ajax.send, @@ -185,6 +191,7 @@ window.wp = window.wp || {}; Attachment = media.model.Attachment = Backbone.Model.extend({ /** * Triggered when attachment details change + * Overrides Backbone.Model.sync * * @param {string} method * @param {wp.media.model.Attachment} model @@ -271,8 +278,9 @@ window.wp = window.wp || {}; /** * Convert date strings into Date objects. * - * @param {Object} resp - * @returns {Object} + * @param {Object} resp The raw response object, typically returned by fetch() + * @returns {Object} The modified response object, which is the attributes hash + * to be set on the model. */ parse: function( resp ) { if ( ! resp ) { @@ -284,8 +292,8 @@ window.wp = window.wp || {}; return resp; }, /** - * @param {Object} data - * @param {Object} options + * @param {Object} data The properties to be saved. + * @param {Object} options Sync options. e.g. patch, wait, success, error. * * @this Backbone.Model * @@ -309,6 +317,7 @@ window.wp = window.wp || {}; } }, { /** + * @static * @param {Object} attrs * @returns {wp.media.model.Attachment} */ @@ -316,6 +325,7 @@ window.wp = window.wp || {}; return Attachments.all.push( attrs ); }, /** + * @static * @param {string} id * @param {Backbone.Model|undefined} attachment * @returns {wp.media.model.Attachment} @@ -618,9 +628,11 @@ window.wp = window.wp || {}; return this.mirroring ? this.mirroring.hasMore() : false; }, /** - * @param {Object} resp - * @param {XMLHttpRequest} xhr - * @returns {Array} + * Overrides Backbone.Collection.parse + * + * @param {Object|Array} resp The raw response Object/Array. + * @param {Object} xhr + * @returns {Array} The array of model attributes to be added to the collection */ parse: function( resp, xhr ) { if ( ! _.isArray( resp ) ) { @@ -690,6 +702,7 @@ window.wp = window.wp || {}; } }, { /** + * @static * @param {Backbone.Model} a * @param {Backbone.Model} b * @param {Object} options @@ -716,13 +729,19 @@ window.wp = window.wp || {}; return ( 'DESC' === order ) ? compare( a, b, ac, bc ) : compare( b, a, bc, ac ); }, - + /** + * @namespace + */ filters: { /** + * @static * Note that this client-side searching is *not* equivalent * to our server-side searching. * * @param {wp.media.model.Attachment} attachment + * + * @this wp.media.model.Attachments + * * @returns {Boolean} */ search: function( attachment ) { @@ -736,7 +755,11 @@ window.wp = window.wp || {}; }, this ); }, /** + * @static * @param {wp.media.model.Attachment} attachment + * + * @this wp.media.model.Attachments + * * @returns {Boolean} */ type: function( attachment ) { @@ -744,7 +767,11 @@ window.wp = window.wp || {}; return ! type || -1 !== type.indexOf( attachment.get('type') ); }, /** + * @static * @param {wp.media.model.Attachment} attachment + * + * @this wp.media.model.Attachments + * * @returns {Boolean} */ uploadedTo: function( attachment ) { @@ -759,6 +786,7 @@ window.wp = window.wp || {}; }); /** + * @static * @member {wp.media.model.Attachments} */ Attachments.all = new Attachments(); @@ -877,6 +905,9 @@ window.wp = window.wp || {}; }); }, /** + * Overrides Backbone.Collection.sync + * Overrides wp.media.model.Attachments.sync + * * @param {String} method * @param {Backbone.Model} model * @param {Object} [options={}] @@ -915,15 +946,22 @@ window.wp = window.wp || {}; } } }, { + /** + * @readonly + */ defaultProps: { orderby: 'date', order: 'DESC' }, - + /** + * @readonly + */ defaultArgs: { posts_per_page: 40 }, - + /** + * @readonly + */ orderby: { allowed: [ 'name', 'author', 'date', 'title', 'modified', 'uploadedTo', 'id', 'post__in', 'menuOrder' ], valuemap: { @@ -932,7 +970,9 @@ window.wp = window.wp || {}; 'menuOrder': 'menu_order ID' } }, - + /** + * @readonly + */ propmap: { 'search': 's', 'type': 'post_mime_type', @@ -940,7 +980,9 @@ window.wp = window.wp || {}; 'menuOrder': 'menu_order', 'uploadedTo': 'post_parent' }, - + /** + * @static + */ // Caches query objects so queries can be easily reused. get: (function(){ /** @@ -1047,6 +1089,9 @@ window.wp = window.wp || {}; * If the workflow does not support multiple * selected attachments, reset the selection. * + * Overrides Backbone.Collection.add + * Overrides wp.media.model.Attachments.add + * * @param {Array} models * @param {Object} options * @returns {wp.media.model.Attachment[]}