From 3cae028b47f83c88401663b88a183703b3f93e94 Mon Sep 17 00:00:00 2001 From: Andrea Fercia Date: Mon, 31 Aug 2026 11:25:27 +0200 Subject: [PATCH] Lint JSDocs part 3 --- src/js/_enqueues/wp/media/models.js | 8 ++-- src/js/_enqueues/wp/media/views.js | 2 +- src/js/_enqueues/wp/widgets/custom-html.js | 2 + src/js/_enqueues/wp/widgets/media-gallery.js | 2 +- src/js/_enqueues/wp/widgets/media-image.js | 2 +- src/js/_enqueues/wp/widgets/media.js | 2 + src/js/_enqueues/wp/widgets/text.js | 2 + src/js/media/controllers/collection-add.js | 4 +- src/js/media/controllers/collection-edit.js | 8 ++-- src/js/media/controllers/cropper.js | 1 + src/js/media/controllers/edit-image.js | 2 +- src/js/media/controllers/embed.js | 6 +-- src/js/media/controllers/featured-image.js | 4 +- src/js/media/controllers/image-details.js | 6 +-- src/js/media/controllers/library.js | 10 ++--- src/js/media/controllers/media-library.js | 2 +- src/js/media/controllers/region.js | 8 ++-- src/js/media/controllers/replace-image.js | 6 +-- src/js/media/controllers/state-machine.js | 4 +- src/js/media/controllers/state.js | 1 + src/js/media/models/attachment.js | 6 +-- src/js/media/models/attachments.js | 39 ++++++++++---------- src/js/media/models/post-image.js | 4 +- src/js/media/models/query.js | 22 ++++++----- src/js/media/models/selection.js | 4 +- 25 files changed, 83 insertions(+), 74 deletions(-) diff --git a/src/js/_enqueues/wp/media/models.js b/src/js/_enqueues/wp/media/models.js index edca0a14f2113..f184ebdba60ad 100644 --- a/src/js/_enqueues/wp/media/models.js +++ b/src/js/_enqueues/wp/media/models.js @@ -17,7 +17,7 @@ window.wp = window.wp || {}; * @namespace * * @param {Object} attributes The properties passed to the main media controller. - * @return {wp.media.view.MediaFrame} A media workflow. + * @return {void|wp.media.view.MediaFrame} A media workflow. */ media = wp.media = function( attributes ) { var MediaFrame = media.view.MediaFrame, @@ -137,7 +137,7 @@ _.extend( media, /** @lends wp.media */{ * Scales a set of dimensions to fit within bounding dimensions. * * @param {Object} dimensions - * @return {Object} + * @return {Object} The scaled dimensions. */ fit: function( dimensions ) { var width = dimensions.width, @@ -209,7 +209,7 @@ _.extend( media, /** @lends wp.media */{ * * @static * @param {string} id A string used to identify a model. - * @return {wp.media.model.Attachment} + * @return {wp.media.model.Attachment} The attachment model for the given id. */ media.attachment = function( id ) { return Attachment.get( id ); @@ -229,7 +229,7 @@ Attachments.all = new Attachments(); * Shorthand for creating a new Attachments Query. * * @param {Object} [props] - * @return {wp.media.model.Attachments} + * @return {wp.media.model.Attachments} A collection of attachments matching the query. */ media.query = function( props ) { return new Attachments( null, { diff --git a/src/js/_enqueues/wp/media/views.js b/src/js/_enqueues/wp/media/views.js index d87046fcf0e2b..2f845bb7a82c5 100644 --- a/src/js/_enqueues/wp/media/views.js +++ b/src/js/_enqueues/wp/media/views.js @@ -49,7 +49,7 @@ media.events = _.extend( {}, Backbone.Events ); * * @param {string} selector * @param {number} sensitivity - * @return {Promise} + * @return {Promise} A promise that resolves when the transition has completed. */ media.transition = function( selector, sensitivity ) { var deferred = $.Deferred(); diff --git a/src/js/_enqueues/wp/widgets/custom-html.js b/src/js/_enqueues/wp/widgets/custom-html.js index 0f1fde1642e94..984233ecddfcb 100644 --- a/src/js/_enqueues/wp/widgets/custom-html.js +++ b/src/js/_enqueues/wp/widgets/custom-html.js @@ -9,6 +9,8 @@ /** * @namespace wp.customHtmlWidget * @memberOf wp + * + * @param {JQueryStatic} $ The jQuery object. */ wp.customHtmlWidgets = ( function( $ ) { 'use strict'; diff --git a/src/js/_enqueues/wp/widgets/media-gallery.js b/src/js/_enqueues/wp/widgets/media-gallery.js index 020e9787a0f38..497fecd0fbd42 100644 --- a/src/js/_enqueues/wp/widgets/media-gallery.js +++ b/src/js/_enqueues/wp/widgets/media-gallery.js @@ -69,7 +69,7 @@ * View events. * * @since 4.9.0 - * @type {object} + * @type {Object} */ events: _.extend( {}, component.MediaWidgetControl.prototype.events, { 'click .media-widget-gallery-preview': 'editMedia' diff --git a/src/js/_enqueues/wp/widgets/media-image.js b/src/js/_enqueues/wp/widgets/media-image.js index 7d15eff1f8cf1..c16600c022c2f 100644 --- a/src/js/_enqueues/wp/widgets/media-image.js +++ b/src/js/_enqueues/wp/widgets/media-image.js @@ -31,7 +31,7 @@ /** * View events. * - * @type {object} + * @type {Object} */ events: _.extend( {}, component.MediaWidgetControl.prototype.events, { 'click .media-widget-preview.populated': 'editMedia' diff --git a/src/js/_enqueues/wp/widgets/media.js b/src/js/_enqueues/wp/widgets/media.js index d67e71fc664ee..66ec8e4306554 100644 --- a/src/js/_enqueues/wp/widgets/media.js +++ b/src/js/_enqueues/wp/widgets/media.js @@ -7,6 +7,8 @@ /** * @namespace wp.mediaWidgets * @memberOf wp + * + * @param {JQueryStatic} $ The jQuery object. */ wp.mediaWidgets = ( function( $ ) { 'use strict'; diff --git a/src/js/_enqueues/wp/widgets/text.js b/src/js/_enqueues/wp/widgets/text.js index 48d72475eebe3..df09ab40974ef 100644 --- a/src/js/_enqueues/wp/widgets/text.js +++ b/src/js/_enqueues/wp/widgets/text.js @@ -7,6 +7,8 @@ /** * @namespace wp.textWidgets + * + * @param {JQueryStatic} $ The jQuery object. */ wp.textWidgets = ( function( $ ) { 'use strict'; diff --git a/src/js/media/controllers/collection-add.js b/src/js/media/controllers/collection-add.js index 1c0a8067c9d24..537657429dc7f 100644 --- a/src/js/media/controllers/collection-add.js +++ b/src/js/media/controllers/collection-add.js @@ -14,7 +14,7 @@ var Selection = wp.media.model.Selection, * @augments wp.media.controller.State * @augments Backbone.Model * - * @param {object} [attributes] The attributes hash passed to the state. + * @param {Object} [attributes] The attributes hash passed to the state. * @param {string} [attributes.id=library] Unique identifier. * @param {string} attributes.title Title for the state. Displays in the frame's title region. * @param {boolean|string} [attributes.multiple=add] Whether multi-select is enabled. Accepts 'add' or true. @@ -33,7 +33,7 @@ var Selection = wp.media.model.Selection, * @param {boolean} [attributes.sortable=true] Whether the Attachments should be sortable. Depends on the orderby property being set to menuOrder on the attachments collection. * @param {boolean} [attributes.autoSelect=true] Whether an uploaded attachment should be automatically added to the selection. * @param {boolean} [attributes.contentUserSetting=true] Whether the content region's mode should be set and persisted per user. - * @param {int} [attributes.priority=100] The priority for the state link in the media menu. + * @param {number} [attributes.priority=100] The priority for the state link in the media menu. * @param {boolean} [attributes.syncSelection=false] Whether the Attachments selection should be persisted from the last state. * Defaults to false because for this state, because the library of the Edit Gallery state is the selection. * @param {string} attributes.type The collection's media type. (e.g. 'video'). diff --git a/src/js/media/controllers/collection-edit.js b/src/js/media/controllers/collection-edit.js index 1c4478f258512..f89a9a2ed27a3 100644 --- a/src/js/media/controllers/collection-edit.js +++ b/src/js/media/controllers/collection-edit.js @@ -16,7 +16,7 @@ var Library = wp.media.controller.Library, * @augments wp.media.controller.State * @augments Backbone.Model * - * @param {object} [attributes] The attributes hash passed to the state. + * @param {Object} [attributes] The attributes hash passed to the state. * @param {string} attributes.title Title for the state. Displays in the media menu and the frame's title region. * @param {wp.media.model.Attachments} [attributes.library] The attachments collection to edit. * If one is not supplied, an empty media.model.Selection collection is created. @@ -29,9 +29,9 @@ var Library = wp.media.controller.Library, * @param {boolean} [attributes.describe=true] Whether to offer UI to describe the attachments - e.g. captioning images in a gallery. * @param {boolean} [attributes.dragInfo=true] Whether to show instructional text about the attachments being sortable. * @param {boolean} [attributes.dragInfoText] Instructional text about the attachments being sortable. - * @param {int} [attributes.idealColumnWidth=170] The ideal column width in pixels for attachments. + * @param {number} [attributes.idealColumnWidth=170] The ideal column width in pixels for attachments. * @param {boolean} [attributes.editing=false] Whether the gallery is being created, or editing an existing instance. - * @param {int} [attributes.priority=60] The priority for the state link in the media menu. + * @param {number} [attributes.priority=60] The priority for the state link in the media menu. * @param {boolean} [attributes.syncSelection=false] Whether the Attachments selection should be persisted from the last state. * Defaults to false for this state, because the library passed in *is* the selection. * @param {view} [attributes.SettingsView] The view to edit the collection instance settings (e.g. Playlist settings with "Show tracklist" checkbox). @@ -117,7 +117,7 @@ CollectionEdit = Library.extend(/** @lends wp.media.controller.CollectionEdit.pr * * @since 3.9.0 * - * @param {wp.media.view.attachmentsBrowser} The attachments browser view. + * @param {wp.media.view.attachmentsBrowser} attachmentsBrowserView The attachments browser view. */ renderSettings: function( attachmentsBrowserView ) { var library = this.get('library'), diff --git a/src/js/media/controllers/cropper.js b/src/js/media/controllers/cropper.js index 2685f743ea8c7..0921839224eb0 100644 --- a/src/js/media/controllers/cropper.js +++ b/src/js/media/controllers/cropper.js @@ -170,6 +170,7 @@ Cropper = wp.media.controller.State.extend(/** @lends wp.media.controller.Croppe * * @since 4.2.0 * + * @param {wp.media.model.Attachment} attachment The image attachment. * @return {$.promise} A jQuery promise with the custom header crop details. */ doCrop: function( attachment ) { diff --git a/src/js/media/controllers/edit-image.js b/src/js/media/controllers/edit-image.js index cdc29487df0fd..828cec6aaaa22 100644 --- a/src/js/media/controllers/edit-image.js +++ b/src/js/media/controllers/edit-image.js @@ -12,7 +12,7 @@ var l10n = wp.media.view.l10n, * @augments wp.media.controller.State * @augments Backbone.Model * - * @param {object} attributes The attributes hash passed to the state. + * @param {Object} attributes The attributes hash passed to the state. * @param {wp.media.model.Attachment} attributes.model The attachment. * @param {string} [attributes.id=edit-image] Unique identifier. * @param {string} [attributes.title=Edit Image] Title for the state. Displays in the media menu and the frame's title region. diff --git a/src/js/media/controllers/embed.js b/src/js/media/controllers/embed.js index d6614ed24d8dc..3c33769704c68 100644 --- a/src/js/media/controllers/embed.js +++ b/src/js/media/controllers/embed.js @@ -13,17 +13,17 @@ var l10n = wp.media.view.l10n, * @augments wp.media.controller.State * @augments Backbone.Model * - * @param {object} attributes The attributes hash passed to the state. + * @param {Object} attributes The attributes hash passed to the state. * @param {string} [attributes.id=embed] Unique identifier. * @param {string} [attributes.title=Insert From URL] Title for the state. Displays in the media menu and the frame's title region. * @param {string} [attributes.content=embed] Initial mode for the content region. * @param {string} [attributes.menu=default] Initial mode for the menu region. * @param {string} [attributes.toolbar=main-embed] Initial mode for the toolbar region. * @param {string} [attributes.menu=false] Initial mode for the menu region. - * @param {int} [attributes.priority=120] The priority for the state link in the media menu. + * @param {number} [attributes.priority=120] The priority for the state link in the media menu. * @param {string} [attributes.type=link] The type of embed. Currently only link is supported. * @param {string} [attributes.url] The embed URL. - * @param {object} [attributes.metadata={}] Properties of the embed, which will override attributes.url if set. + * @param {Object} [attributes.metadata={}] Properties of the embed, which will override attributes.url if set. */ Embed = wp.media.controller.State.extend(/** @lends wp.media.controller.Embed.prototype */{ defaults: { diff --git a/src/js/media/controllers/featured-image.js b/src/js/media/controllers/featured-image.js index 0f87ff659c42c..f5ab034e28b0d 100644 --- a/src/js/media/controllers/featured-image.js +++ b/src/js/media/controllers/featured-image.js @@ -15,7 +15,7 @@ var Attachment = wp.media.model.Attachment, * @augments wp.media.controller.State * @augments Backbone.Model * - * @param {object} [attributes] The attributes hash passed to the state. + * @param {Object} [attributes] The attributes hash passed to the state. * @param {string} [attributes.id=featured-image] Unique identifier. * @param {string} [attributes.title=Set Featured Image] Title for the state. Displays in the media menu and the frame's title region. * @param {wp.media.model.Attachments} [attributes.library] The attachments collection to browse. @@ -26,7 +26,7 @@ var Attachment = wp.media.model.Attachment, * @param {string} [attributes.menu=default] Initial mode for the menu region. * @param {string} [attributes.router=browse] Initial mode for the router region. * @param {string} [attributes.toolbar=featured-image] Initial mode for the toolbar region. - * @param {int} [attributes.priority=60] The priority for the state link in the media menu. + * @param {number} [attributes.priority=60] The priority for the state link in the media menu. * @param {boolean} [attributes.searchable=true] Whether the library is searchable. * @param {boolean|string} [attributes.filterable=false] Whether the library is filterable, and if so what filters should be shown. * Accepts 'all', 'uploaded', or 'unattached'. diff --git a/src/js/media/controllers/image-details.js b/src/js/media/controllers/image-details.js index 2d4689e5a3c65..3d1725472a6eb 100644 --- a/src/js/media/controllers/image-details.js +++ b/src/js/media/controllers/image-details.js @@ -15,7 +15,7 @@ var State = wp.media.controller.State, * @augments wp.media.controller.State * @augments Backbone.Model * - * @param {object} [attributes] The attributes hash passed to the state. + * @param {Object} [attributes] The attributes hash passed to the state. * @param {string} [attributes.id=image-details] Unique identifier. * @param {string} [attributes.title=Image Details] Title for the state. Displays in the frame's title region. * @param {wp.media.model.Attachment} attributes.image The image's model. @@ -24,7 +24,7 @@ var State = wp.media.controller.State, * @param {string|false} [attributes.router=false] Initial mode for the router region. * @param {string|false} [attributes.toolbar=image-details] Initial mode for the toolbar region. * @param {boolean} [attributes.editing=false] Unused. - * @param {int} [attributes.priority=60] Unused. + * @param {number} [attributes.priority=60] Unused. * * @todo This state inherits some defaults from media.controller.Library.prototype.defaults, * however this may not do anything. @@ -44,7 +44,7 @@ ImageDetails = State.extend(/** @lends wp.media.controller.ImageDetails.prototyp /** * @since 3.9.0 * - * @param options Attributes + * @param {Object} options Attributes. */ initialize: function( options ) { this.image = options.image; diff --git a/src/js/media/controllers/library.js b/src/js/media/controllers/library.js index db77c8dae8241..375326a357d20 100644 --- a/src/js/media/controllers/library.js +++ b/src/js/media/controllers/library.js @@ -15,7 +15,7 @@ var l10n = wp.media.view.l10n, * @augments Backbone.Model * @mixes media.selectionSync * - * @param {object} [attributes] The attributes hash passed to the state. + * @param {Object} [attributes] The attributes hash passed to the state. * @param {string} [attributes.id=library] Unique identifier. * @param {string} [attributes.title=Media library] Title for the state. Displays in the media menu and the frame's title region. * @param {wp.media.model.Attachments} [attributes.library] The attachments collection to browse. @@ -153,7 +153,7 @@ Library = wp.media.controller.State.extend(/** @lends wp.media.controller.Librar * @since 3.5.0 * * @param {wp.media.model.Attachment} attachment - * @return {Backbone.Model} + * @return {Backbone.Model} A model representing the display settings for the attachment. */ display: function( attachment ) { var displays = this._displays; @@ -170,7 +170,7 @@ Library = wp.media.controller.State.extend(/** @lends wp.media.controller.Librar * @since 3.6.0 * * @param {wp.media.model.Attachment} attachment - * @return {Object} + * @return {Object} The default display settings for the attachment. */ defaultDisplaySettings: function( attachment ) { var settings = _.clone( this._defaultDisplaySettings ); @@ -191,7 +191,7 @@ Library = wp.media.controller.State.extend(/** @lends wp.media.controller.Librar * @since 4.4.1 * * @param {wp.media.model.Attachment} attachment - * @return {boolean} + * @return {boolean} True if the attachment is an image, false otherwise. */ isImageAttachment: function( attachment ) { // If uploading, we know the filename but not the mime type. @@ -208,7 +208,7 @@ Library = wp.media.controller.State.extend(/** @lends wp.media.controller.Librar * @since 3.6.0 * * @param {wp.media.model.Attachment} attachment - * @return {boolean} + * @return {boolean} True if the attachment can be embedded, false otherwise. */ canEmbed: function( attachment ) { // If uploading, we know the filename but not the mime type. diff --git a/src/js/media/controllers/media-library.js b/src/js/media/controllers/media-library.js index 1f0fe744673ab..fd86e411696b8 100644 --- a/src/js/media/controllers/media-library.js +++ b/src/js/media/controllers/media-library.js @@ -24,7 +24,7 @@ MediaLibrary = Library.extend(/** @lends wp.media.controller.MediaLibrary.protot /** * @since 3.9.0 * - * @param options + * @param {Object} options Attributes. */ initialize: function( options ) { this.media = options.media; diff --git a/src/js/media/controllers/region.js b/src/js/media/controllers/region.js index c211bc9c8de25..982182469b12a 100644 --- a/src/js/media/controllers/region.js +++ b/src/js/media/controllers/region.js @@ -94,8 +94,8 @@ _.extend( Region.prototype,/** @lends wp.media.controller.Region.prototype */{ * Region view creation takes place in an event callback on the frame. * * @event wp.media.controller.Region#create - * @type {object} - * @property {object} view + * @type {Object} + * @property {Object} view */ this.trigger( 'create', set ); view = set.view; @@ -106,7 +106,7 @@ _.extend( Region.prototype,/** @lends wp.media.controller.Region.prototype */{ * Region view creation takes place in an event callback on the frame. * * @event wp.media.controller.Region#render - * @type {object} + * @type {Object} */ this.trigger( 'render', view ); if ( view ) { @@ -120,7 +120,7 @@ _.extend( Region.prototype,/** @lends wp.media.controller.Region.prototype */{ * * @since 3.5.0 * - * @return {wp.media.View} + * @return {wp.media.View} Returns the region's view. */ get: function() { return this.view.views.first( this.selector ); diff --git a/src/js/media/controllers/replace-image.js b/src/js/media/controllers/replace-image.js index 46dce6d1bab86..441f0926fb462 100644 --- a/src/js/media/controllers/replace-image.js +++ b/src/js/media/controllers/replace-image.js @@ -14,7 +14,7 @@ var Library = wp.media.controller.Library, * @augments wp.media.controller.State * @augments Backbone.Model * - * @param {object} [attributes] The attributes hash passed to the state. + * @param {Object} [attributes] The attributes hash passed to the state. * @param {string} [attributes.id=replace-image] Unique identifier. * @param {string} [attributes.title=Replace Image] Title for the state. Displays in the media menu and the frame's title region. * @param {wp.media.model.Attachments} [attributes.library] The attachments collection to browse. @@ -25,7 +25,7 @@ var Library = wp.media.controller.Library, * @param {string} [attributes.menu=default] Initial mode for the menu region. * @param {string} [attributes.router=browse] Initial mode for the router region. * @param {string} [attributes.toolbar=replace] Initial mode for the toolbar region. - * @param {int} [attributes.priority=60] The priority for the state link in the media menu. + * @param {number} [attributes.priority=60] The priority for the state link in the media menu. * @param {boolean} [attributes.searchable=true] Whether the library is searchable. * @param {boolean|string} [attributes.filterable=uploaded] Whether the library is filterable, and if so what filters should be shown. * Accepts 'all', 'uploaded', or 'unattached'. @@ -50,7 +50,7 @@ ReplaceImage = Library.extend(/** @lends wp.media.controller.ReplaceImage.protot /** * @since 3.9.0 * - * @param options + * @param {Object} options Attributes. */ initialize: function( options ) { var library, comparator; diff --git a/src/js/media/controllers/state-machine.js b/src/js/media/controllers/state-machine.js index 50ebb10e6c739..9d7086944e16d 100644 --- a/src/js/media/controllers/state-machine.js +++ b/src/js/media/controllers/state-machine.js @@ -93,8 +93,8 @@ _.extend( StateMachine.prototype, Backbone.Events,/** @lends wp.media.controller * * @since 3.5.0 * - * @return {wp.media.controller.State} Returns a State model from - * the StateMachine collection. + * @return {void|wp.media.controller.State} Returns a State model from + * the StateMachine collection. */ lastState: function() { if ( this._lastState ) { diff --git a/src/js/media/controllers/state.js b/src/js/media/controllers/state.js index bbc9b3826b2e7..270ed47e41efe 100644 --- a/src/js/media/controllers/state.js +++ b/src/js/media/controllers/state.js @@ -129,6 +129,7 @@ var State = Backbone.Model.extend(/** @lends wp.media.controller.State.prototype }, /** + * @param {media.view.Title} view The title view. * @since 3.5.0 * @access private */ diff --git a/src/js/media/models/attachment.js b/src/js/media/models/attachment.js index 267624b7d6c48..037b0972bbcf9 100644 --- a/src/js/media/models/attachment.js +++ b/src/js/media/models/attachment.js @@ -18,7 +18,7 @@ Attachment = Backbone.Model.extend(/** @lends wp.media.model.Attachment.prototyp * @param {wp.media.model.Attachment} model * @param {Object} [options={}] * - * @return {Promise} + * @return {jQuery.Promise} A jQuery Promise that is resolved or rejected based on the success of the sync operation. */ sync: function( method, model, options ) { // If the attachment does not yet have an `id`, return an instantly @@ -118,7 +118,7 @@ Attachment = Backbone.Model.extend(/** @lends wp.media.model.Attachment.prototyp * * @this Backbone.Model * - * @return {Promise} + * @return {jQuery.Promise} A jQuery Promise that is resolved or rejected based on the success of the sync operation. */ saveCompat: function( data, options ) { var model = this; @@ -143,7 +143,7 @@ Attachment = Backbone.Model.extend(/** @lends wp.media.model.Attachment.prototyp * @static * * @param {Object} attrs - * @return {wp.media.model.Attachment} + * @return {wp.media.model.Attachment} The newly created attachment model. */ create: function( attrs ) { var Attachments = wp.media.model.Attachments; diff --git a/src/js/media/models/attachments.js b/src/js/media/models/attachments.js index fb31ba09ab9d6..887afc4366d1a 100644 --- a/src/js/media/models/attachments.js +++ b/src/js/media/models/attachments.js @@ -12,14 +12,14 @@ * @class * @augments Backbone.Collection * - * @param {array} [models] Models to initialize with the collection. - * @param {object} [options] Options hash for the collection. - * @param {string} [options.props] Options hash for the initial query properties. - * @param {string} [options.props.order] Initial order (ASC or DESC) for the collection. - * @param {string} [options.props.orderby] Initial attribute key to order the collection by. - * @param {string} [options.props.query] Whether the collection is linked to an attachments query. - * @param {string} [options.observe] - * @param {string} [options.filters] + * @param {wp.media.model.Attachment[]} [models] Models to initialize with the collection. + * @param {Object} [options] Options hash for the collection. + * @param {string} [options.props] Options hash for the initial query properties. + * @param {string} [options.props.order] Initial order (ASC or DESC) for the collection. + * @param {string} [options.props.orderby] Initial attribute key to order the collection by. + * @param {string} [options.props.query] Whether the collection is linked to an attachments query. + * @param {string} [options.observe] An attachments collection to observe and mirror. + * @param {string} [options.filters] Filters to apply to the collection. * */ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachments.prototype */{ @@ -161,7 +161,7 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen * Checks whether an attachment is valid. * * @param {wp.media.model.Attachment} attachment - * @return {boolean} + * @return {boolean} True if the attachment is valid, false otherwise. */ validator: function( attachment ) { @@ -218,7 +218,7 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen * Start observing another attachments collection change events * and replicate them on this collection. * - * @param {wp.media.model.Attachments} The attachments collection to observe. + * @param {wp.media.model.Attachments} attachments The attachments collection to observe. * @return {wp.media.model.Attachments} Returns itself to allow chaining. */ observe: function( attachments ) { @@ -233,7 +233,7 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen /** * Stop replicating collection change events from another attachments collection. * - * @param {wp.media.model.Attachments} The attachments collection to stop observing. + * @param {wp.media.model.Attachments} attachments The attachments collection to stop observing. * @return {wp.media.model.Attachments} Returns itself to allow chaining. */ unobserve: function( attachments ) { @@ -306,7 +306,7 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen * Start mirroring another attachments collection, clearing out any models already * in the collection. * - * @param {wp.media.model.Attachments} The attachments collection to mirror. + * @param {wp.media.model.Attachments} attachments The attachments collection to mirror. * @return {wp.media.model.Attachments} Returns itself to allow chaining. */ mirror: function( attachments ) { @@ -351,7 +351,7 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen * server persistence by itself. * * @param {Object} options - * @return {Promise} + * @return {Promise} A promise that resolves when the request is complete. */ more: function( options ) { var deferred = jQuery.Deferred(), @@ -386,7 +386,7 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen * and forwards to its `hasMore` method. This collection class doesn't have * server persistence by itself. * - * @return {boolean} + * @return {boolean} True if there are more attachments to retrieve, false otherwise. */ hasMore: function() { return this.mirroring ? this.mirroring.hasMore() : false; @@ -452,7 +452,6 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen * If the collection is a query, create and mirror an Attachments Query collection. * * @access private - * @param {Boolean} refresh Deprecated, refresh parameter no longer used. */ _requery: function() { var props; @@ -465,7 +464,7 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen * If this collection is sorted by `menuOrder`, recalculates and saves * the menu order to the database. * - * @return {undefined|Promise} + * @return {undefined|Promise} Returns a promise if the menu order is saved, otherwise undefined. */ saveMenuOrder: function() { if ( 'menuOrder' !== this.props.get('orderby') ) { @@ -542,7 +541,7 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen * * @this wp.media.model.Attachments * - * @return {Boolean} + * @return {boolean} True if the attachment matches the search filter, false otherwise. */ search: function( attachment ) { if ( ! this.props.get('search') ) { @@ -560,7 +559,7 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen * * @this wp.media.model.Attachments * - * @return {boolean} + * @return {boolean} True if the attachment matches the type filter, false otherwise. */ type: function( attachment ) { var type = this.props.get('type'), atts = attachment.toJSON(), mime, found; @@ -587,7 +586,7 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen * * @this wp.media.model.Attachments * - * @return {boolean} + * @return {boolean} True if the attachment matches the uploadedTo filter, false otherwise. */ uploadedTo: function( attachment ) { var uploadedTo = this.props.get('uploadedTo'); @@ -603,7 +602,7 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen * * @this wp.media.model.Attachments * - * @return {boolean} + * @return {boolean} True if the attachment matches the status filter, false otherwise. */ status: function( attachment ) { var status = this.props.get('status'); diff --git a/src/js/media/models/post-image.js b/src/js/media/models/post-image.js index 1642f42e2a52b..d5972e9be41f2 100644 --- a/src/js/media/models/post-image.js +++ b/src/js/media/models/post-image.js @@ -10,8 +10,8 @@ * @class * @augments Backbone.Model * - * @param {int} [attributes] Initial model attributes. - * @param {int} [attributes.attachment_id] ID of the attachment. + * @param {number} [attributes] Initial model attributes. + * @param {number} [attributes.attachment_id] ID of the attachment. **/ var PostImage = Backbone.Model.extend(/** @lends wp.media.model.PostImage.prototype */{ diff --git a/src/js/media/models/query.js b/src/js/media/models/query.js index 3c47215c39833..46895a09b20b6 100644 --- a/src/js/media/models/query.js +++ b/src/js/media/models/query.js @@ -15,10 +15,10 @@ var Attachments = wp.media.model.Attachments, * @augments wp.media.model.Attachments * @augments Backbone.Collection * - * @param {array} [models] Models to initialize with the collection. - * @param {object} [options] Options hash. - * @param {object} [options.args] Attachments query arguments. - * @param {object} [options.args.posts_per_page] + * @param {wp.media.model.Attachment[]} [models] Models to initialize with the collection. + * @param {Object} [options] Options hash. + * @param {Object} [options.args] Attachments query arguments. + * @param {Object} [options.args.posts_per_page] */ Query = Attachments.extend(/** @lends wp.media.model.Query.prototype */{ /** @@ -86,7 +86,7 @@ Query = Attachments.extend(/** @lends wp.media.model.Query.prototype */{ * Whether there are more attachments that haven't been sync'd from the server * that match the collection's query. * - * @return {boolean} + * @return {boolean} True if there are more attachments to fetch, false otherwise. */ hasMore: function() { return this._hasMore; @@ -95,7 +95,7 @@ Query = Attachments.extend(/** @lends wp.media.model.Query.prototype */{ * Fetch more attachments from the server for the collection. * * @param {Object} [options={}] - * @return {Promise} + * @return {Promise} A promise that resolves when the fetch is complete. */ more: function( options ) { var query = this; @@ -125,7 +125,7 @@ Query = Attachments.extend(/** @lends wp.media.model.Query.prototype */{ * @param {string} method * @param {Backbone.Model} model * @param {Object} [options={}] - * @return {Promise} + * @return {Promise} A promise that resolves when the sync is complete. */ sync: function( method, model, options ) { var args, fallback; @@ -210,9 +210,9 @@ Query = Attachments.extend(/** @lends wp.media.model.Query.prototype */{ * Caches query objects and reuses where possible. * * @static - * @method + * @function * - * @param {object} [props] + * @param {Object} [props] * @param {Object} [props.order] * @param {Object} [props.orderby] * @param {Object} [props.include] @@ -236,7 +236,9 @@ Query = Attachments.extend(/** @lends wp.media.model.Query.prototype */{ var queries = []; /** - * @return {Query} + * @param {Object} [props] + * @param {Object} [options] + * @return {Query} A new Attachments Query collection. */ return function( props, options ) { var args = {}, diff --git a/src/js/media/models/selection.js b/src/js/media/models/selection.js index a2fc899c8bbec..b7ae7bbadd816 100644 --- a/src/js/media/models/selection.js +++ b/src/js/media/models/selection.js @@ -37,7 +37,7 @@ Selection = Attachments.extend(/** @lends wp.media.model.Selection.prototype */{ * * @param {Array} models * @param {Object} options - * @return {wp.media.model.Attachment[]} + * @return {wp.media.model.Attachment[]} The added attachments. */ add: function( models, options ) { if ( ! this.multiple ) { @@ -57,7 +57,7 @@ Selection = Attachments.extend(/** @lends wp.media.model.Selection.prototype */{ * @fires wp.media.model.Selection#selection:single * @fires wp.media.model.Selection#selection:unsingle * - * @return {Backbone.Model} + * @return {Backbone.Model} The single model in the selection, or the last model as a fallback. */ single: function( model ) { var previous = this._single;