Changeset 27032

Timestamp:

01/25/2014 08:55:47 AM (13 years ago)

Author:

wonderboymusic

Message:

Add some inline docs to methods in media-models.js - particularly around @param and @returns.

See #26870.

File:

• trunk/src/wp-includes/js/media-models.js (modified) (10 diffs)

trunk/src/wp-includes/js/media-models.js

@@ -153 +153 @@
                  * @param {Number} [length=30]
                  * @param {String} [replacement=…]
-                 * @returns {String}
+                 * @returns {String} The string, unless length is greater than string.length.
                  */
                 truncate: function( string, length, replacement ) {
@@ -176 +176 @@
          *
          * @static
-         * @param {String} id
+         * @param {String} id A string used to identify a model.
          * @returns {wp.media.model.Attachment}
          */
@@ -318 +318 @@
         }, {
                 /**
+                 * Add a model to the end of the static 'all' collection and return it.
+                 *
                  * @static
                  * @param {Object} attrs
@@ -326 +328 @@
                 },
                 /**
+                 * Retrieve a model, or add it to the end of the static 'all' collection before returning it.
+                 *
                  * @static
-                 * @param {string} id
+                 * @param {string} id A string used to identify a model.
                  * @param {Backbone.Model|undefined} attachment
                  * @returns {wp.media.model.Attachment}
@@ -348 +352 @@
                 model: Attachment,
                 /**
-                 * @param {Array|Object} models
+                 * @param {Array} [models=[]] Array of models used to populate the collection.
                  * @param {Object} [options={}]
                  */
@@ -499 +503 @@
                  * @param {wp.media.model.Attachments} attachments
                  * @param {object} [options={}]
+                 *
+                 * @fires wp.media.model.Attachments#reset
+                 *
                  * @returns {wp.media.model.Attachments} Returns itself to allow chaining
                  */
@@ -704 +711 @@
                 /**
                  * @static
+                 * Overrides Backbone.Collection.comparator
+                 *
                  * @param {Backbone.Model} a
                  * @param {Backbone.Model} b
                  * @param {Object} options
-                 * @returns {Number}
+                 * @returns {Number} -1 if the first model should come before the second,
+                 *    0 if they are of the same rank and
+                 *    1 if the first model should come after.
                  */
                 comparator: function( a, b, options ) {
@@ -821 +832 @@
                  * @global wp.Uploader
                  *
-                 * @param {Array} models
+                 * @param {Array} [models=[]] Array of models used to populate the collection.
                  * @param {Object} [options={}]
                  */
@@ -983 +994 @@
                 /**
                  * @static
+                 * @method
+                 *
+                 * @returns {wp.media.model.Query} A new query.
                  */
                 // Caches query objects so queries can be easily reused.
@@ -1072 +1086 @@
                  * it receives no parameters.
                  *
-                 * @param {Array} models
-                 * @param {Object} options
+                 * @param {Array} [models=[]] Array of models used to populate the collection.
+                 * @param {Object} [options={}]
                  */
                 initialize: function( models, options ) {