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

@@ -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
+		 * @param {Object} resp The raw response object, typically returned by fetch()
-		 * @returns {Object}
+		 * @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} data The properties to be saved.
-		 * @param {Object} options
+		 * @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
+		 * Overrides Backbone.Collection.parse
-		 * @param {XMLHttpRequest} xhr
+		 *
-		 * @returns {Array}
+		 * @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[]}