diff --git a/Gruntfile.js b/Gruntfile.js
index 2e09a71dd0456..9f34d13b57721 100644
--- a/Gruntfile.js
+++ b/Gruntfile.js
@@ -1,5 +1,4 @@
/* jshint node:true */
-/* eslint-env es6 */
/* globals Set */
var webpackConfig = require( './webpack.config' );
var installChanged = require( 'install-changed' );
diff --git a/src/js/_enqueues/admin/application-passwords.js b/src/js/_enqueues/admin/application-passwords.js
index c79cdb8b4037f..2e6f2e82c1eed 100644
--- a/src/js/_enqueues/admin/application-passwords.js
+++ b/src/js/_enqueues/admin/application-passwords.js
@@ -2,6 +2,9 @@
* @output wp-admin/js/application-passwords.js
*/
+/**
+ * @param {JQueryStatic} $ The jQuery object.
+ */
( function( $ ) {
var $appPassSection = $( '#application-passwords-section' ),
$newAppPassForm = $appPassSection.find( '.create-application-password' ),
@@ -188,7 +191,7 @@
*
* @param {string} message The message to display.
* @param {string} type The notice type. Either 'success' or 'error'.
- * @returns {jQuery} The notice element.
+ * @return {jQuery} The notice element.
*/
function addNotice( message, type ) {
var $notice = $( '' )
diff --git a/src/js/_enqueues/admin/comment.js b/src/js/_enqueues/admin/comment.js
index b31f174bab5fe..d2ebafbcf4834 100644
--- a/src/js/_enqueues/admin/comment.js
+++ b/src/js/_enqueues/admin/comment.js
@@ -9,7 +9,7 @@
*
* @since 2.5.0
*
- * @param {jQuery} $ The jQuery object.
+ * @param {JQueryStatic} $ The jQuery object.
*/
jQuery( function($) {
diff --git a/src/js/_enqueues/admin/common.js b/src/js/_enqueues/admin/common.js
index c3d49310e8897..735a9aeeaabef 100644
--- a/src/js/_enqueues/admin/common.js
+++ b/src/js/_enqueues/admin/common.js
@@ -8,9 +8,9 @@
/**
* Adds common WordPress functionality to the window.
*
- * @param {jQuery} $ jQuery object.
- * @param {Object} window The window object.
- * @param {mixed} undefined Unused.
+ * @param {JQueryStatic} $ The jQuery object.
+ * @param {Object} window The window object.
+ * @param {*} undefined Unused.
*/
( function( $, window, undefined ) {
var $document = $( document ),
@@ -58,10 +58,10 @@ function deprecatedProperty( propName, version, replacement ) {
* @since 5.6.0 Added the `version` parameter.
*
* @param {string} name The name of the object, i.e. commonL10n.
- * @param {object} l10nObject The object to deprecate the properties on.
+ * @param {Object} l10nObject The object to deprecate the properties on.
* @param {string} version The version of WordPress that deprecated the property.
*
- * @return {object} The object with all its properties deprecated.
+ * @return {Object} The object with all its properties deprecated.
*/
function deprecateL10nObject( name, l10nObject, version ) {
var deprecatedObject = {};
@@ -476,8 +476,6 @@ window.columns = {
* Gets the checked column toggles from the screen options.
*
* @since 3.0.0
- *
- * @return {string} String containing the checked column names.
*/
useCheckboxesForHidden : function() {
this.hidden = function(){
@@ -557,7 +555,7 @@ window.showNotice = {
*
* @since 2.7.0
*
- * @param text The text to display in the message.
+ * @param {string} text The text to display in the message.
*/
note : function(text) {
alert(text);
@@ -1263,6 +1261,7 @@ $( function() {
/**
* Triggers the primary submit when then secondary submit is clicked.
*
+ * @param {SubmitEvent} e The event object.
* @since 5.7.0
*
* @return {void}
@@ -2245,6 +2244,8 @@ $( function( $ ) {
* plugin icon images in the update plugins table.
*
* @since 6.4.0
+ *
+ * @return {Object} Public methods.
*/
(function() {
// Private variables and methods.
diff --git a/src/js/_enqueues/admin/custom-background.js b/src/js/_enqueues/admin/custom-background.js
index f83db00af03b4..d8ef84e618bc1 100644
--- a/src/js/_enqueues/admin/custom-background.js
+++ b/src/js/_enqueues/admin/custom-background.js
@@ -10,6 +10,8 @@
* @since 3.0.0
*
* @requires jQuery
+ *
+ * @param {JQueryStatic} $ The jQuery object.
*/
(function($) {
$( function() {
diff --git a/src/js/_enqueues/admin/custom-header.js b/src/js/_enqueues/admin/custom-header.js
index 367756ef8758b..40f9be4f35962 100644
--- a/src/js/_enqueues/admin/custom-header.js
+++ b/src/js/_enqueues/admin/custom-header.js
@@ -11,6 +11,8 @@
*
* @deprecated 4.1.0 The page this is used on is never linked to from the UI.
* Setting a custom header is completely handled by the Customizer.
+ *
+ * @param {JQueryStatic} $ The jQuery object.
*/
(function($) {
var frame;
diff --git a/src/js/_enqueues/admin/edit-comments.js b/src/js/_enqueues/admin/edit-comments.js
index 78ee78de759ff..4320c8e00f0ea 100644
--- a/src/js/_enqueues/admin/edit-comments.js
+++ b/src/js/_enqueues/admin/edit-comments.js
@@ -1,14 +1,14 @@
+/* global adminCommentsSettings, thousandsSeparator, list_args, QTags, ajaxurl, wpAjax */
+/* global commentReply, theExtraList, theList, setCommentsList */
+
/**
* Handles updating and editing comments.
- *
- * @file This file contains functionality for the admin comments page.
- * @since 2.1.0
* @output wp-admin/js/edit-comments.js
*/
-/* global adminCommentsSettings, thousandsSeparator, list_args, QTags, ajaxurl, wpAjax */
-/* global commentReply, theExtraList, theList, setCommentsList */
-
+/**
+ * @param {JQueryStatic} $ The jQuery object.
+ */
(function($) {
var getCount, updateCount, updateCountText, updatePending, updateApproved,
updateHtmlTitle, updateDashboardText, updateInModerationText, adminTitle = document.title,
diff --git a/src/js/_enqueues/admin/inline-edit-post.js b/src/js/_enqueues/admin/inline-edit-post.js
index 6e6e3bef606ed..7f469137fc1bd 100644
--- a/src/js/_enqueues/admin/inline-edit-post.js
+++ b/src/js/_enqueues/admin/inline-edit-post.js
@@ -21,6 +21,9 @@ window.wp = window.wp || {};
* @property {string} type The type of inline editor.
* @property {string} what The prefix before the post ID.
*
+ * @param {JQueryStatic} $ The jQuery object.
+ * @param {wp} wp The WordPress global object.
+ *
*/
( function( $, wp ) {
@@ -188,6 +191,8 @@ window.wp = window.wp || {};
* @since 2.7.0
*
* @memberof inlineEditPost
+ *
+ * @return {void|false} Returns false if no checkboxes are checked, otherwise does not return anything.
*/
setBulk : function(){
var te = '', type = this.type, c = true;
diff --git a/src/js/_enqueues/admin/inline-edit-tax.js b/src/js/_enqueues/admin/inline-edit-tax.js
index 86e3498cd1eac..620533455f6be 100644
--- a/src/js/_enqueues/admin/inline-edit-tax.js
+++ b/src/js/_enqueues/admin/inline-edit-tax.js
@@ -16,6 +16,9 @@ window.wp = window.wp || {};
* @property {string} type The type of inline edit we are currently on.
* @property {string} what The type property with a hash prefixed and a dash
* suffixed.
+ *
+ * @param {JQueryStatic} $ The jQuery object.
+ * @param {Object} wp The WordPress object.
*/
( function( $, wp ) {
diff --git a/src/js/_enqueues/admin/post.js b/src/js/_enqueues/admin/post.js
index 445e79d8a6f05..2eac2f828397a 100644
--- a/src/js/_enqueues/admin/post.js
+++ b/src/js/_enqueues/admin/post.js
@@ -14,6 +14,9 @@ window.makeSlugeditClickable = window.editPermalink = function(){};
// Make sure the wp object exists.
window.wp = window.wp || {};
+/**
+ * @param {JQueryStatic} $ The jQuery object.
+ */
( function( $ ) {
var titleHasFocus = false,
__ = wp.i18n.__;
@@ -254,6 +257,8 @@ window.wp = window.wp || {};
/**
* Heartbeat refresh nonces.
+ *
+ * @param {JQueryStatic} $ The jQuery object.
*/
(function($) {
var check, timeout;
@@ -300,6 +305,8 @@ window.wp = window.wp || {};
/**
* All post and postbox controls and functionality.
+ *
+ * @param {JQueryStatic} $ The jQuery object.
*/
jQuery( function($) {
var stamp, visibility, $submitButtons, updateVisibility, updateText,
@@ -620,11 +627,11 @@ jQuery( function($) {
});
/**
- * Before adding a new taxonomy, disable submit button.
+ * Disables the submit button before adding a new taxonomy.
*
* @param {Object} s Taxonomy object which will be added.
*
- * @return {Object}
+ * @return {Object} Taxonomy object with additional data to be sent to the server.
*/
catAddBefore = function( s ) {
if ( !$('#new'+taxonomy).val() ) {
@@ -1322,6 +1329,9 @@ jQuery( function($) {
/**
* TinyMCE word count display
+ *
+ * @param {JQueryStatic} $ The jQuery object.
+ * @param {wp.utils.WordCounter} counter The WordCounter object.
*/
( function( $, counter ) {
$( function() {
diff --git a/src/js/_enqueues/admin/site-health.js b/src/js/_enqueues/admin/site-health.js
index 57d5c9cbcf289..98aaedc427c0e 100644
--- a/src/js/_enqueues/admin/site-health.js
+++ b/src/js/_enqueues/admin/site-health.js
@@ -85,9 +85,9 @@ jQuery( function( $ ) {
*
* @since 5.6.0
*
- * @param {Object} issue
+ * @param {Object} issue The issue data to validate.
*
- * @return {boolean}
+ * @return {boolean} True if the issue data is valid, false otherwise.
*/
function validateIssueData( issue ) {
// Expected minimum format of a valid SiteHealth test response.
@@ -137,6 +137,7 @@ jQuery( function( $ ) {
* @since 5.2.0
*
* @param {Object} issue The issue data.
+ * @return {void|boolean} True if the issue was appended, false otherwise.
*/
function appendIssue( issue ) {
var template = wp.template( 'health-check-issue' ),
@@ -346,6 +347,8 @@ jQuery( function( $ ) {
/**
* Add the details of a failed asynchronous test to the list of test results.
*
+ * @param {string} url
+ * @param {string} description
* @since 5.6.0
*/
function addFailedSiteHealthCheckNotice( url, description ) {
diff --git a/src/js/_enqueues/admin/site-icon.js b/src/js/_enqueues/admin/site-icon.js
index a4f94797a5a48..59a098dc08aac 100644
--- a/src/js/_enqueues/admin/site-icon.js
+++ b/src/js/_enqueues/admin/site-icon.js
@@ -141,7 +141,7 @@
*
* @since 6.5.0
*
- * @param {array} attributes The attributes for the attachment.
+ * @param {Object} attributes The attributes for the attachment.
*/
function switchToUpdate( attributes ) {
var i18nAppAlternativeString, i18nBrowserAlternativeString;
diff --git a/src/js/_enqueues/admin/tags-suggest.js b/src/js/_enqueues/admin/tags-suggest.js
index d439f06ef0de8..08bea1464bbbe 100644
--- a/src/js/_enqueues/admin/tags-suggest.js
+++ b/src/js/_enqueues/admin/tags-suggest.js
@@ -2,6 +2,8 @@
* Default settings for jQuery UI Autocomplete for use with non-hierarchical taxonomies.
*
* @output wp-admin/js/tags-suggest.js
+ *
+ * @param {JQueryStatic} $ The jQuery object.
*/
( function( $ ) {
var tempID = 0;
diff --git a/src/js/_enqueues/admin/tags.js b/src/js/_enqueues/admin/tags.js
index 88e38b6926309..8d449ca986863 100644
--- a/src/js/_enqueues/admin/tags.js
+++ b/src/js/_enqueues/admin/tags.js
@@ -9,6 +9,9 @@
/* global ajaxurl, wpAjax, showNotice, validateForm */
+ /**
+ * @param {JQueryStatic} $ The jQuery object.
+ */
jQuery( function($) {
var addingTerm = false;
diff --git a/src/js/_enqueues/admin/user-profile.js b/src/js/_enqueues/admin/user-profile.js
index 6a6be6745e357..c2bd1a78dc179 100644
--- a/src/js/_enqueues/admin/user-profile.js
+++ b/src/js/_enqueues/admin/user-profile.js
@@ -1,8 +1,12 @@
+/* global ajaxurl, pwsL10n, userProfileL10n, ClipboardJS */
+
/**
* @output wp-admin/js/user-profile.js
*/
-/* global ajaxurl, pwsL10n, userProfileL10n, ClipboardJS */
+/**
+ * @param {JQueryStatic} $ The jQuery object.
+ */
(function($) {
var updateLock = false,
isSubmitting = false,
@@ -160,7 +164,7 @@
*
* @param {jQuery Object} $this The button element: the message will be inserted
* above this button
- * @param {bool} success Whether the message is a success message.
+ * @param {boolean} success Whether the message is a success message.
* @param {string} message The message to insert.
*/
function addInlineNotice( $this, success, message ) {
@@ -400,7 +404,7 @@
* On macOS Safari and Firefox, the native warning is preferred,
* so this function returns false to suppress custom warnings.
*
- * @param {KeyboardEvent} e The keydown event object.
+ * @param {KeyboardEvent} event The keydown event object.
*
* @return {boolean} True if Caps Lock is on, false otherwise.
*/
diff --git a/src/js/_enqueues/admin/widgets.js b/src/js/_enqueues/admin/widgets.js
index e8fc42507d382..cbd8f8dd4a222 100644
--- a/src/js/_enqueues/admin/widgets.js
+++ b/src/js/_enqueues/admin/widgets.js
@@ -11,14 +11,14 @@ window.wpWidgets = {
/**
* A closed Sidebar that gets a Widget dragged over it.
*
- * @var {element|null}
+ * @member {jQuery|null}
*/
hoveredSidebar: null,
/**
* Lookup of which widgets have had change events triggered.
*
- * @var {object}
+ * @member {Object}
*/
dirtyWidgets: {},
@@ -751,7 +751,7 @@ $( function(){ wpWidgets.init(); } );
* @since 4.9.0
* @deprecated 5.5.0
*
- * @type {object}
+ * @type {Object}
*/
wpWidgets.l10n = wpWidgets.l10n || {
save: '',
diff --git a/src/js/_enqueues/lib/accordion.js b/src/js/_enqueues/lib/accordion.js
index 9b52b179b22a6..12daff74a0daf 100644
--- a/src/js/_enqueues/lib/accordion.js
+++ b/src/js/_enqueues/lib/accordion.js
@@ -29,6 +29,9 @@
* @output wp-admin/js/accordion.js
*/
+/**
+ * @param {JQueryStatic} $ The jQuery object.
+ */
( function( $ ){
$( function () {
diff --git a/src/js/_enqueues/lib/admin-bar.js b/src/js/_enqueues/lib/admin-bar.js
index 619694db37f5c..3d6f4e3c8b94d 100644
--- a/src/js/_enqueues/lib/admin-bar.js
+++ b/src/js/_enqueues/lib/admin-bar.js
@@ -206,7 +206,7 @@
* @since 5.3.1 Use querySelector to clean up the function.
*
* @param {Event} event The click event.
- * @return {boolean} Returns false to prevent default click behavior.
+ * @return {boolean|void} False to prevent default action.
*/
function clickShortlink( event ) {
var wrapper = event.target.parentNode,
@@ -397,6 +397,8 @@
*
* @param {HTMLElement} el Element to get parent.
* @param {string} selector CSS selector to match.
+ *
+ * @return {HTMLElement|null} The closest matching element or null if not found.
*/
function getClosest( el, selector ) {
if ( ! window.Element.prototype.matches ) {
diff --git a/src/js/_enqueues/lib/auth-check.js b/src/js/_enqueues/lib/auth-check.js
index ff64573639a25..f01b14b35e386 100644
--- a/src/js/_enqueues/lib/auth-check.js
+++ b/src/js/_enqueues/lib/auth-check.js
@@ -4,6 +4,9 @@
* @output wp-includes/js/wp-auth-check.js
*/
+/**
+ * @param {JQueryStatic} $ The jQuery object.
+ */
( function( $ ) {
var wrap,
tempHidden,
diff --git a/src/js/_enqueues/lib/codemirror/javascript-lint.js b/src/js/_enqueues/lib/codemirror/javascript-lint.js
index 2c96798a20ae3..74c4cbacc0c5f 100644
--- a/src/js/_enqueues/lib/codemirror/javascript-lint.js
+++ b/src/js/_enqueues/lib/codemirror/javascript-lint.js
@@ -12,10 +12,10 @@ import CodeMirror from 'codemirror';
* @see https://codemirror.net/5/doc/manual.html#addon_lint
*
* @typedef {Object} CodeMirrorLintError
- * @property {string} message - Error message.
- * @property {'error'} severity - Severity.
- * @property {CodeMirror.Position} from - From position.
- * @property {CodeMirror.Position} to - To position.
+ * @property {string} message Error message.
+ * @property {'error'} severity Severity.
+ * @property {CodeMirror.Position} from From position.
+ * @property {CodeMirror.Position} to To position.
*/
/**
@@ -25,12 +25,12 @@ import CodeMirror from 'codemirror';
* @see https://www.npmjs.com/package/espree#options
*
* @typedef {Object} SupportedJSHintOptions
- * @property {import('espree').Options['ecmaVersion']} [esversion] - "This option is used to specify the ECMAScript version to which the code must adhere."
- * @property {boolean} [es5] - "This option enables syntax first defined in the ECMAScript 5.1 specification. This includes allowing reserved keywords as object properties."
- * @property {boolean} [es3] - "This option tells JSHint that your code needs to adhere to ECMAScript 3 specification. Use this option if you need your program to be executable in older browsers—such as Internet Explorer 6/7/8/9—and other legacy JavaScript environments."
- * @property {boolean} [module] - "This option informs JSHint that the input code describes an ECMAScript 6 module. All module code is interpreted as strict mode code."
- * @property {'implied'} [strict] - "This option requires the code to run in ECMAScript 5's strict mode."
- * @property {string} [espreeModuleUrl] - The URL to the espree script module.
+ * @property {import('espree').Options['ecmaVersion']} [esversion] "This option is used to specify the ECMAScript version to which the code must adhere."
+ * @property {boolean} [es5] "This option enables syntax first defined in the ECMAScript 5.1 specification. This includes allowing reserved keywords as object properties."
+ * @property {boolean} [es3] "This option tells JSHint that your code needs to adhere to ECMAScript 3 specification. Use this option if you need your program to be executable in older browsers—such as Internet Explorer 6/7/8/9—and other legacy JavaScript environments."
+ * @property {boolean} [module] "This option informs JSHint that the input code describes an ECMAScript 6 module. All module code is interpreted as strict mode code."
+ * @property {'implied'} [strict] "This option requires the code to run in ECMAScript 5's strict mode."
+ * @property {string} [espreeModuleUrl] The URL to the espree script module.
*/
/**
@@ -38,9 +38,9 @@ import CodeMirror from 'codemirror';
*
* @since 7.0.0
*
- * @param {string} text - Source.
- * @param {SupportedJSHintOptions} options - Linting options.
- * @returns {Promise}
+ * @param {string} text Source.
+ * @param {SupportedJSHintOptions} options Linting options.
+ * @return {Promise} Linting errors.
*/
async function validator( text, options ) {
if ( ! options.espreeModuleUrl ) {
@@ -84,14 +84,8 @@ CodeMirror.registerHelper( 'lint', 'javascript', validator );
*
* @since 7.0.0
*
- * @param {SupportedJSHintOptions} options - Linting options for JSHint.
- * @return {{
- * ecmaVersion?: import('espree').Options['ecmaVersion'],
- * sourceType?: 'module'|'script',
- * ecmaFeatures?: {
- * impliedStrict?: true
- * }
- * }}
+ * @param {SupportedJSHintOptions} options Linting options for JSHint.
+ * @return {import('espree').Options} Options for Espree.
*/
function getEspreeOptions( options ) {
/** @type {{ impliedStrict?: true }} */
@@ -112,7 +106,7 @@ function getEspreeOptions( options ) {
*
* @since 7.0.0
*
- * @param {SupportedJSHintOptions} options - Options.
+ * @param {SupportedJSHintOptions} options Options.
* @return {import('espree').Options['ecmaVersion']} ECMAScript version.
*/
function getEcmaVersion( options ) {
diff --git a/src/js/_enqueues/lib/color-picker.js b/src/js/_enqueues/lib/color-picker.js
index 600e0235b3bdb..51d68cbff4473 100644
--- a/src/js/_enqueues/lib/color-picker.js
+++ b/src/js/_enqueues/lib/color-picker.js
@@ -1,7 +1,13 @@
/**
* @output wp-admin/js/color-picker.js
+ *
+ * @since 3.5.0
*/
+/**
+ * @param {JQueryStatic} $ The jQuery object.
+ * @param {undefined} undef The undefined value.
+ */
( function( $, undef ) {
var ColorPicker,
@@ -320,11 +326,11 @@
/**
* Returns the iris object if no new color is provided. If a new color is provided, it sets the new color.
*
- * @param newColor {string|*} The new color to use. Can be undefined.
+ * @param {string|*} newColor The new color to use. Can be undefined.
*
* @since 3.5.0
*
- * @return {string} The element's color.
+ * @return {string|void} The element's color.
*/
color: function( newColor ) {
if ( newColor === undef ) {
@@ -332,15 +338,16 @@
}
this.element.iris( 'option', 'color', newColor );
},
+
/**
* Returns the iris object if no new default color is provided.
* If a new default color is provided, it sets the new default color.
*
- * @param newDefaultColor {string|*} The new default color to use. Can be undefined.
+ * @param {string|*} newDefaultColor The new default color to use. Can be undefined.
*
* @since 3.5.0
*
- * @return {boolean|string} The element's color.
+ * @return {string|void} The element's default color.
*/
defaultColor: function( newDefaultColor ) {
if ( newDefaultColor === undef ) {
diff --git a/src/js/_enqueues/lib/comment-reply.js b/src/js/_enqueues/lib/comment-reply.js
index fabd579f5afc2..6ebc181551f79 100644
--- a/src/js/_enqueues/lib/comment-reply.js
+++ b/src/js/_enqueues/lib/comment-reply.js
@@ -127,7 +127,7 @@ window.addComment = ( function( window ) {
*
* @param {HTMLElement} context The parent DOM element to search for links.
*
- * @return {HTMLCollection|NodeList|Array}
+ * @return {HTMLCollection|NodeList} The collection of links.
*/
function replyLinks( context ) {
var selectorClass = config.commentReplyClass;
@@ -270,10 +270,10 @@ window.addComment = ( function( window ) {
*
* @since 5.1.0
*
- * @param {HTMLElement} Element DOM element with the attribute.
- * @param {string} Attribute the attribute to get.
+ * @param {HTMLElement} element DOM element with the attribute.
+ * @param {string} attribute The attribute to get.
*
- * @return {string}
+ * @return {string} The value of the attribute.
*/
function getDataAttribute( element, attribute ) {
if ( supportsDataset ) {
@@ -291,7 +291,9 @@ window.addComment = ( function( window ) {
*
* @since 5.1.0
*
- * @param {HTMLElement} The requested element.
+ * @param {string} elementId The requested element.
+ *
+ * @return {HTMLElement} The element with the given ID.
*/
function getElementById( elementId ) {
return document.getElementById( elementId );
@@ -309,6 +311,8 @@ window.addComment = ( function( window ) {
* @param {string} respondId HTML ID of 'respond' element.
* @param {string} postId Database ID of the post.
* @param {string} replyTo Form heading content.
+ *
+ * @return {void|boolean} Returns false for backward compatibility with third party commenting systems hooking into this function.
*/
function moveForm( addBelowId, commentId, respondId, postId, replyTo ) {
// Get elements based on their IDs.
diff --git a/src/js/_enqueues/lib/cookies.js b/src/js/_enqueues/lib/cookies.js
index 66d920affaa85..30a29d496a02e 100644
--- a/src/js/_enqueues/lib/cookies.js
+++ b/src/js/_enqueues/lib/cookies.js
@@ -40,6 +40,9 @@ window.wpCookies = {
/**
* Get a multi-values cookie.
* Returns a JS object with the name: 'value' pairs.
+ *
+ * @param {string} name The name of the cookie.
+ * @return {Object} The cookie values as a JS object.
*/
getHash: function( name ) {
var cookie = this.get( name ), values;
@@ -59,6 +62,13 @@ window.wpCookies = {
* Set a multi-values cookie.
*
* 'values_obj' is the JS object that is stored. It is encoded as URI in wpCookies.set().
+ *
+ * @param {string} name The name of the cookie.
+ * @param {Object} values_obj The values to store in the cookie.
+ * @param {number|Date} [expires] Optional. Expiration time in seconds or a Date object.
+ * @param {string} [path] Optional. The path on the server in which the cookie will be available on.
+ * @param {string} [domain] Optional. The domain that the cookie is available to.
+ * @param {boolean} [secure] Optional. Whether the cookie should only be transmitted over a secure HTTPS connection.
*/
setHash: function( name, values_obj, expires, path, domain, secure ) {
var str = '';
@@ -72,6 +82,8 @@ window.wpCookies = {
/**
* Get a cookie.
+ * @param {string} name The name of the cookie.
+ * @return {void|string} The cookie value.
*/
get: function( name ) {
var e, b,
@@ -107,7 +119,14 @@ window.wpCookies = {
* Set a cookie.
*
* The 'expires' arg can be either a JS Date() object set to the expiration date (back-compat)
- * or the number of seconds until expiration
+ * or the number of seconds until expiration.
+ *
+ * @param {string} name The name of the cookie.
+ * @param {string} value The value of the cookie.
+ * @param {number|Date} [expires] Optional. Expiration time in seconds or a Date object.
+ * @param {string} [path] Optional. The path on the server in which the cookie will be available on.
+ * @param {string} [domain] Optional. The domain that the cookie is available to.
+ * @param {boolean} [secure] Optional. Whether the cookie should only be transmitted over a secure HTTPS connection.
*/
set: function( name, value, expires, path, domain, secure ) {
var d = new Date();
@@ -132,6 +151,11 @@ window.wpCookies = {
* Remove a cookie.
*
* This is done by setting it to an empty value and setting the expiration time in the past.
+ *
+ * @param {string} name The name of the cookie.
+ * @param {string} [path] Optional. The path on the server in which the cookie will be available on.
+ * @param {string} [domain] Optional. The domain that the cookie is available to.
+ * @param {boolean} [secure] Optional. Whether the cookie should only be transmitted over a secure HTTPS connection.
*/
remove: function( name, path, domain, secure ) {
this.set( name, '', -1000, path, domain, secure );
diff --git a/src/js/_enqueues/lib/emoji-loader.js b/src/js/_enqueues/lib/emoji-loader.js
index 4882107670174..86963a2a3af24 100644
--- a/src/js/_enqueues/lib/emoji-loader.js
+++ b/src/js/_enqueues/lib/emoji-loader.js
@@ -2,14 +2,12 @@
* @output wp-includes/js/wp-emoji-loader.js
*/
-/* eslint-env es6 */
-
// Note: This is loaded as a script module, so there is no need for an IIFE to prevent pollution of the global scope.
/**
* Emoji Settings as exported in PHP via _print_emoji_detection_script().
* @typedef WPEmojiSettings
- * @type {object}
+ * @type {Object}
* @property {?object} source
* @property {?string} source.concatemoji
* @property {?string} source.twemoji
@@ -29,7 +27,7 @@ window._wpemojiSettings = settings;
/**
* Support tests.
* @typedef SupportTests
- * @type {object}
+ * @type {Object}
* @property {?boolean} flag
* @property {?boolean} emoji
*/
@@ -44,7 +42,7 @@ const tests = [ 'flag', 'emoji' ];
*
* @private
*
- * @returns {boolean}
+ * @return {boolean} True if the browser supports offloading to a Worker.
*/
function supportsWorkerOffloading() {
return (
@@ -58,7 +56,7 @@ function supportsWorkerOffloading() {
/**
* @typedef SessionSupportTests
- * @type {object}
+ * @type {Object}
* @property {number} timestamp
* @property {SupportTests} supportTests
*/
@@ -70,7 +68,7 @@ function supportsWorkerOffloading() {
*
* @private
*
- * @returns {?SupportTests} Support tests, or null if not set or older than 1 week.
+ * @return {?SupportTests} Support tests, or null if not set or older than 1 week.
*/
function getSessionSupportTests() {
try {
diff --git a/src/js/_enqueues/lib/image-edit.js b/src/js/_enqueues/lib/image-edit.js
index d1603051d7078..0431551aeb615 100644
--- a/src/js/_enqueues/lib/image-edit.js
+++ b/src/js/_enqueues/lib/image-edit.js
@@ -1,12 +1,13 @@
+ /* global ajaxurl, confirm */
+
/**
* The functions necessary for editing images.
*
* @since 2.9.0
* @output wp-admin/js/image-edit.js
+ *
+ * @param {JQueryStatic} $ The jQuery object.
*/
-
- /* global ajaxurl, confirm */
-
(function($) {
var __ = wp.i18n.__;
@@ -23,6 +24,10 @@
/**
* Enable crop tool.
+ *
+ * @param {number} postid The post ID.
+ * @param {string} nonce The nonce to verify the request.
+ * @param {HTMLElement} cropButton The crop button element.
*/
toggleCropTool: function( postid, nonce, cropButton ) {
var img = $( '#image-preview-' + postid ),
@@ -64,6 +69,10 @@
/**
* Handle crop tool clicks.
+ *
+ * @param {number} postid The post ID.
+ * @param {string} nonce The nonce to verify the request.
+ * @param {HTMLElement} cropButton The crop button element.
*/
handleCropToolClick: function( postid, nonce, cropButton ) {
@@ -269,8 +278,6 @@
*
* @memberof imageEdit
*
- * @param {HTMLElement} el The activated control element.
- *
* @return {boolean} Always returns false.
*/
monitorPopup : function() {
@@ -567,7 +574,7 @@
*
* @param {number} postid The post ID.
* @param {string} nonce The nonce to verify the request.
- * @param {function} callback Function to execute when the image is loaded.
+ * @param {Function} callback Function to execute when the image is loaded.
*
* @return {void}
*/
@@ -1002,7 +1009,7 @@
* @param {Object} img jQuery object representing the image.
* @param {Object} c The selection.
*
- * @return {Object}
+ * @return {void}
*/
onSelectEnd: function(img, c) {
imageEdit.setCropSelection(postid, c);
@@ -1047,7 +1054,7 @@
* @param {number} postid The post ID.
* @param {Object} c The selection.
*
- * @return {boolean}
+ * @return {boolean|void} Returns false if the selection is invalid.
*/
setCropSelection : function(postid, c) {
var sel,
@@ -1197,7 +1204,7 @@
* @param {string} nonce The nonce.
* @param {Object} t The target element.
*
- * @return {boolean}
+ * @return {boolean|void} Returns false if the rotate button is disabled.
*/
rotate : function(angle, postid, nonce, t) {
if ( $(t).hasClass('disabled') ) {
@@ -1224,7 +1231,7 @@
* @param {string} nonce The nonce.
* @param {Object} t The target element.
*
- * @return {boolean}
+ * @return {boolean|void} Returns false if the flip button is disabled.
*/
flip : function (axis, postid, nonce, t) {
if ( $(t).hasClass('disabled') ) {
diff --git a/src/js/_enqueues/lib/list-revisions.js b/src/js/_enqueues/lib/list-revisions.js
index db0485ef97a08..80ce2e909f287 100644
--- a/src/js/_enqueues/lib/list-revisions.js
+++ b/src/js/_enqueues/lib/list-revisions.js
@@ -1,4 +1,5 @@
/**
+ * @param {Window} w The global window object.
* @output wp-includes/js/wp-list-revisions.js
*/
diff --git a/src/js/_enqueues/lib/lists.js b/src/js/_enqueues/lib/lists.js
index d7e888c85b9ab..c81848ff5db5d 100644
--- a/src/js/_enqueues/lib/lists.js
+++ b/src/js/_enqueues/lib/lists.js
@@ -5,7 +5,7 @@
/* global ajaxurl, wpAjax */
/**
- * @param {jQuery} $ jQuery object.
+ * @param {JQueryStatic} $ The jQuery object.
*/
( function( $ ) {
var functions = {
@@ -22,7 +22,7 @@ var functions = {
wpList = {
/**
- * @member {object}
+ * @member {Object}
*/
settings: {
@@ -108,9 +108,9 @@ wpList = {
* Callback that's run before a request is made.
*
* @callback wpList~confirm
- * @param {object} this
+ * @param {Object} this
* @param {HTMLElement} list The list DOM element.
- * @param {object} settings Settings for the current list.
+ * @param {Object} settings Settings for the current list.
* @param {string} action The type of action to perform: 'add', 'delete', or 'dim'.
* @param {string} backgroundColor Background color of the list's DOM element.
* @return {boolean} Whether to proceed with the action or not.
@@ -123,7 +123,7 @@ wpList = {
* Allows to cancel the request.
*
* @callback wpList~addBefore
- * @param {object} settings Settings for the Ajax request.
+ * @param {Object} settings Settings for the Ajax request.
* @return {object|boolean} Settings for the Ajax request or false to abort.
*/
addBefore: null,
@@ -133,11 +133,11 @@ wpList = {
*
* @callback wpList~addAfter
* @param {XML} returnedResponse Raw response returned from the server.
- * @param {object} settings Settings for the Ajax request.
+ * @param {Object} settings Settings for the Ajax request.
* @param {jqXHR} settings.xml jQuery XMLHttpRequest object.
* @param {string} settings.status Status of the request: 'success', 'notmodified', 'nocontent', 'error',
* 'timeout', 'abort', or 'parsererror'.
- * @param {object} settings.parsed Parsed response object.
+ * @param {Object} settings.parsed Parsed response object.
*/
addAfter: null,
@@ -147,7 +147,7 @@ wpList = {
* Allows to cancel the request.
*
* @callback wpList~delBefore
- * @param {object} settings Settings for the Ajax request.
+ * @param {Object} settings Settings for the Ajax request.
* @param {HTMLElement} list The list DOM element.
* @return {object|boolean} Settings for the Ajax request or false to abort.
*/
@@ -158,11 +158,11 @@ wpList = {
*
* @callback wpList~delAfter
* @param {XML} returnedResponse Raw response returned from the server.
- * @param {object} settings Settings for the Ajax request.
+ * @param {Object} settings Settings for the Ajax request.
* @param {jqXHR} settings.xml jQuery XMLHttpRequest object.
* @param {string} settings.status Status of the request: 'success', 'notmodified', 'nocontent', 'error',
* 'timeout', 'abort', or 'parsererror'.
- * @param {object} settings.parsed Parsed response object.
+ * @param {Object} settings.parsed Parsed response object.
*/
delAfter: null,
@@ -172,7 +172,7 @@ wpList = {
* Allows to cancel the request.
*
* @callback wpList~dimBefore
- * @param {object} settings Settings for the Ajax request.
+ * @param {Object} settings Settings for the Ajax request.
* @return {object|boolean} Settings for the Ajax request or false to abort.
*/
dimBefore: null,
@@ -182,11 +182,11 @@ wpList = {
*
* @callback wpList~dimAfter
* @param {XML} returnedResponse Raw response returned from the server.
- * @param {object} settings Settings for the Ajax request.
+ * @param {Object} settings Settings for the Ajax request.
* @param {jqXHR} settings.xml jQuery XMLHttpRequest object.
* @param {string} settings.status Status of the request: 'success', 'notmodified', 'nocontent', 'error',
* 'timeout', 'abort', or 'parsererror'.
- * @param {object} settings.parsed Parsed response object.
+ * @param {Object} settings.parsed Parsed response object.
*/
dimAfter: null
},
diff --git a/src/js/_enqueues/lib/nav-menu.js b/src/js/_enqueues/lib/nav-menu.js
index 79917c8447f1a..b3e6b93f0408e 100644
--- a/src/js/_enqueues/lib/nav-menu.js
+++ b/src/js/_enqueues/lib/nav-menu.js
@@ -5,12 +5,14 @@
* @version 2.0.0
*
* @package WordPress
- * @subpackage Administration
* @output wp-admin/js/nav-menu.js
*/
/* global menus, postboxes, columns, isRtl, ajaxurl, wpNavMenu */
+/**
+ * @param {JQueryStatic} $ The jQuery object.
+ */
(function($) {
var api;
@@ -178,7 +180,7 @@
*
* @ignore
*
- * @param jQuery metabox The metabox jQuery object.
+ * @param {Function} processMethod The method to use for adding the menu items. Defaults to api.addMenuItemToBottom.
*/
addSelectedToMenu : function(processMethod) {
if ( 0 === $('#menu-to-edit').length ) {
@@ -339,7 +341,7 @@
}
});
});
-
+
});
},
updateOrderDropdown : function() {
@@ -403,7 +405,7 @@
}
});
-
+
});
}
});
@@ -560,7 +562,7 @@
menu.on( 'change', '.edit-menu-item-parent', function() {
api.changeMenuParent( $( this ) );
});
-
+
// Update menu item order when value is changed.
menu.on( 'change', '.edit-menu-item-order', function() {
api.changeMenuOrder( $( this ) );
@@ -569,10 +571,10 @@
/**
* changeMenuParent( [parentDropdown] )
- *
+ *
* @since 6.7.0
*
- * @param {object} parentDropdown select field
+ * @param {Object} parentDropdown select field
*/
changeMenuParent : function( parentDropdown ) {
var menuItemNewPosition,
@@ -625,10 +627,10 @@
/**
* changeMenuOrder( [OrderDropdown] )
- *
+ *
* @since 6.7.0
*
- * @param {object} orderDropdown select field
+ * @param {Object} orderDropdown select field
*/
changeMenuOrder : function( orderDropdown ) {
var menuItems = $( '#menu-to-edit li' ),
@@ -1159,7 +1161,7 @@
* Handle toggling bulk selection checkboxes for menu items.
*
* @since 5.8.0
- */
+ */
attachBulkSelectButtonListeners : function() {
var that = this;
@@ -1178,7 +1180,7 @@
* Enable bulk selection checkboxes for menu items.
*
* @since 5.8.0
- */
+ */
enableBulkSelection : function() {
var checkbox = $( '#menu-to-edit .menu-item-checkbox' );
@@ -1195,7 +1197,7 @@
* Disable bulk selection checkboxes for menu items.
*
* @since 5.8.0
- */
+ */
disableBulkSelection : function() {
var checkbox = $( '#menu-to-edit .menu-item-checkbox' );
@@ -1219,7 +1221,7 @@
* Listen for state changes on bulk action checkboxes.
*
* @since 5.8.0
- */
+ */
attachMenuCheckBoxListeners : function() {
var that = this;
@@ -1232,7 +1234,7 @@
* Create delete button to remove menu items from collection.
*
* @since 5.8.0
- */
+ */
attachMenuItemDeleteButton : function() {
var that = this;
@@ -1275,7 +1277,7 @@
* List menu items awaiting deletion.
*
* @since 5.8.0
- */
+ */
attachPendingMenuItemsListForDeletion : function() {
$( '#post-body-content' ).on( 'change', '.menu-item-checkbox', function() {
var menuItemName, menuItemType, menuItemID, listedMenuItem;
@@ -1317,7 +1319,7 @@
* Set status of bulk delete checkbox.
*
* @since 5.8.0
- */
+ */
setBulkDeleteCheckboxStatus : function() {
var that = this;
var checkbox = $( '#menu-to-edit .menu-item-checkbox' );
@@ -1341,7 +1343,7 @@
* Set status of menu items removal button.
*
* @since 5.8.0
- */
+ */
setRemoveSelectedButtonStatus : function() {
var button = $( '.menu-items-delete' );
@@ -1419,7 +1421,7 @@
}
/*
- * Reset results when search is less than or equal to
+ * Reset results when search is less than or equal to
* minimum characters for searched term.
*/
if ( q.length <= minSearchLength ) {
@@ -1766,9 +1768,9 @@
/**
* Process the quick search response into a search result
*
- * @param string resp The server response to the query.
- * @param object req The request arguments.
- * @param jQuery panel The tabs panel we're searching in.
+ * @param {string} resp The server response to the query.
+ * @param {Object} req The request arguments.
+ * @param {jQuery} panel The tabs panel we're searching in.
*/
processQuickSearchQueryResponse : function(resp, req, panel) {
var matched, newID,
diff --git a/src/js/_enqueues/lib/pointer.js b/src/js/_enqueues/lib/pointer.js
index 9d043f6dee141..d946d6c015121 100644
--- a/src/js/_enqueues/lib/pointer.js
+++ b/src/js/_enqueues/lib/pointer.js
@@ -4,6 +4,8 @@
/**
* Initializes the wp-pointer widget using jQuery UI Widget Factory.
+ *
+ * @param {JQueryStatic} $ The jQuery object.
*/
(function($){
var identifier = 0,
@@ -146,7 +148,7 @@
*
* @param {Object} event The event that caused the update.
*
- * @return {Promise} Resolves when the update has been executed.
+ * @return {Promise|void} Resolves when the update has been executed.
*/
update: function( event ) {
var self = this,
diff --git a/src/js/_enqueues/lib/quicktags.js b/src/js/_enqueues/lib/quicktags.js
index 4b1a80fa28c94..621fab1058315 100644
--- a/src/js/_enqueues/lib/quicktags.js
+++ b/src/js/_enqueues/lib/quicktags.js
@@ -1,4 +1,3 @@
-
/*
* Quicktags
*
@@ -330,16 +329,16 @@ window.edToolbar = function(){};
* QTags.addButton( 'my_id', 'my button', '', '' );
* QTags.addButton( 'my_id2', 'my button', '
' );
*
- * @param string id Required. Button HTML ID
- * @param string display Required. Button's value="..."
- * @param string|function arg1 Required. Either a starting tag to be inserted like "" or a callback that is executed when the button is clicked.
- * @param string arg2 Optional. Ending tag like ""
- * @param string access_key Deprecated Not used
- * @param string title Optional. Button's title="..."
- * @param int priority Optional. Number representing the desired position of the button in the toolbar. 1 - 9 = first, 11 - 19 = second, 21 - 29 = third, etc.
- * @param string instance Optional. Limit the button to a specific instance of Quicktags, add to all instances if not present.
- * @param attr object Optional. Used to pass additional attributes. Currently supports `ariaLabel` and `ariaLabelClose` (for "close tag" state)
- * @return mixed null or the button object that is needed for back-compat.
+ * @param {string} id Required. Button HTML ID
+ * @param {string} display Required. Button's value="..."
+ * @param {string|Function} arg1 Required. Either a starting tag to be inserted like "" or a callback that is executed when the button is clicked.
+ * @param {string} arg2 Optional. Ending tag like ""
+ * @param {string} [access_key] Deprecated Not used
+ * @param {string} [title] Optional. Button's title="..."
+ * @param {number} [priority] Optional. Number representing the desired position of the button in the toolbar. 1 - 9 = first, 11 - 19 = second, 21 - 29 = third, etc.
+ * @param {string} [instance] Optional. Limit the button to a specific instance of Quicktags, add to all instances if not present.
+ * @param {Object} [attr] Optional. Used to pass additional attributes. Currently supports `ariaLabel` and `ariaLabelClose` (for "close tag" state)
+ * @return {void|Object} Returns the button object if priority is -1, otherwise returns void.
*/
qt.addButton = function( id, display, arg1, arg2, access_key, title, priority, instance, attr ) {
var btn;
@@ -723,26 +722,38 @@ window.edToolbar = function(){};
/**
* Initialize new instance of the Quicktags editor
+ *
+ * @param {Object} settings The settings for the Quicktags editor.
+ * @return {Object} The Quicktags editor instance.
*/
window.quicktags = function(settings) {
return new window.QTags(settings);
};
/**
- * Inserts content at the caret in the active editor (textarea)
+ * Inserts content at the caret in the active editor (textarea).
*
* Added for back compatibility
+ * @param {string} bah The ID of the textarea.
+ * @param {string} txt The content to insert.
* @see QTags.insertContent()
+ * @return {boolean} True if the content was inserted, false otherwise.
*/
window.edInsertContent = function(bah, txt) {
return window.QTags.insertContent(txt);
};
/**
- * Adds a button to all instances of the editor
+ * Adds a button to all instances of the editor.
*
* Added for back compatibility, use QTags.addButton() as it gives more flexibility like type of button, button placement, etc.
+ * @param {string} id The ID of the button.
+ * @param {string} display The display text of the button.
+ * @param {string} tagStart The starting tag.
+ * @param {string} tagEnd The ending tag.
+ * @param {string} access The access key for the button.
* @see QTags.addButton()
+ * @return {void|Object} Returns the button object if priority is -1, otherwise returns void.
*/
window.edButton = function(id, display, tagStart, tagEnd, access) {
return window.QTags.addButton( id, display, tagStart, tagEnd, access, '', -1 );
diff --git a/src/js/_enqueues/wp/api-request.js b/src/js/_enqueues/wp/api-request.js
index 58ef53117903e..3404fc848874c 100644
--- a/src/js/_enqueues/wp/api-request.js
+++ b/src/js/_enqueues/wp/api-request.js
@@ -14,6 +14,9 @@
* @output wp-includes/js/api-request.js
*/
+/**
+ * @param {JQueryStatic} $ The jQuery object.
+ */
( function( $ ) {
var wpApiSettings = window.wpApiSettings;
diff --git a/src/js/_enqueues/wp/api.js b/src/js/_enqueues/wp/api.js
index 9e68d77553c56..8773f4f3acdfe 100644
--- a/src/js/_enqueues/wp/api.js
+++ b/src/js/_enqueues/wp/api.js
@@ -1,4 +1,6 @@
/**
+ * @param {Window} window The global window object.
+ * @param {undefined} undefined The undefined value.
* @output wp-includes/js/wp-api.js
*/
@@ -47,8 +49,7 @@
/**
* Determine model based on API route.
*
- * @param {string} route The API route.
- *
+ * @param {string} route The API route.
* @return {Backbone Model} The model found at given route. Undefined if not found.
*/
wp.api.getModelByRoute = function( route ) {
@@ -60,8 +61,7 @@
/**
* Determine collection based on API route.
*
- * @param {string} route The API route.
- *
+ * @param {string} route The API route.
* @return {Backbone Model} The collection found at given route. Undefined if not found.
*/
wp.api.getCollectionByRoute = function( route ) {
@@ -100,7 +100,9 @@
/**
* Parse date into ISO 8601 format.
*
- * @param {Date} date.
+ * @param {Date} date A date object to parse.
+ *
+ * @return {number} The timestamp of the date.
*/
wp.api.utils.parseISO8601 = function( date ) {
var timestamp, struct, i, k,
@@ -152,6 +154,9 @@
/**
* Helper for capitalizing strings.
+ *
+ * @param {string} str The string to capitalize.
+ * @return {string} The capitalized string.
*/
wp.api.utils.capitalize = function( str ) {
if ( _.isUndefined( str ) ) {
@@ -163,6 +168,9 @@
/**
* Helper function that capitalizes the first word and camel cases any words starting
* after dashes, removing the dashes.
+ *
+ * @param {string} str The string to capitalize and camel case.
+ * @return {string} The capitalized and camel cased string.
*/
wp.api.utils.capitalizeAndCamelCaseDashes = function( str ) {
if ( _.isUndefined( str ) ) {
@@ -175,6 +183,9 @@
/**
* Helper function to camel case the letter after dashes, removing the dashes.
+ *
+ * @param {string} str The string to camel case.
+ * @return {string} The camel cased string.
*/
wp.api.utils.camelCaseDashes = function( str ) {
return str.replace( /-([a-z])/g, function( g ) {
@@ -190,6 +201,7 @@
* Example route `/a/b/c`: part 1 is `c`, part 2 is `b`, part 3 is `a`.
* @param {string} [versionString] Version string, defaults to `wp.api.versionString`.
* @param {boolean} [reverse] Whether to reverse the order when extracting the route part. Optional, default false.
+ * @return {string} The route part.
*/
wp.api.utils.extractRoutePart = function( route, part, versionString, reverse ) {
var routeParts;
@@ -216,6 +228,7 @@
* Extract a parent name from a passed route.
*
* @param {string} route The route to extract a name from.
+ * @return {string} The parent name.
*/
wp.api.utils.extractParentName = function( route ) {
var name,
@@ -291,6 +304,7 @@
* @param {Backbone Model} model The model to attach helpers and mixins to.
* @param {string} modelClassName The classname of the constructed model.
* @param {Object} loadingObjects An object containing the models and collections we are building.
+ * @return {undefined} No return value.
*/
wp.api.utils.addMixinsAndHelpers = function( model, modelClassName, loadingObjects ) {
@@ -320,9 +334,10 @@
* This helper function accepts a field and Date object. It converts the passed Date
* to an ISO string and sets that on the model field.
*
- * @param {Date} date A JavaScript date object. WordPress expects dates in UTC.
- * @param {string} field The date field to set. One of 'date', 'date_gmt', 'date_modified'
- * or 'date_modified_gmt'. Optional, defaults to 'date'.
+ * @param {Date} date A JavaScript date object. WordPress expects dates in UTC.
+ * @param {string} field The date field to set. One of 'date', 'date_gmt', 'date_modified'
+ * or 'date_modified_gmt'. Optional, defaults to 'date'.
+ * @return {void|boolean} False if the field is not a parseable date field, true otherwise.
*/
setDate: function( date, field ) {
var theField = field || 'date';
@@ -341,8 +356,9 @@
* WordPress returns 'date' and 'date_modified' in the timezone of the server as well as
* UTC dates as 'date_gmt' and 'date_modified_gmt'. Draft posts do not include UTC dates.
*
- * @param {string} field The date field to set. One of 'date', 'date_gmt', 'date_modified'
- * or 'date_modified_gmt'. Optional, defaults to 'date'.
+ * @param {string} field The date field to set. One of 'date', 'date_gmt', 'date_modified'
+ * or 'date_modified_gmt'. Optional, defaults to 'date'.
+ * @return {Date|boolean} A JavaScript Date object, or false if the field is not a parseable date field.
*/
getDate: function( field ) {
var theField = field || 'date',
@@ -494,6 +510,9 @@
/**
* Set the model post parent.
+ *
+ * @param {wp.api.collections} collection The collection to set the parent post for.
+ * @param {number} postId The ID of the parent post.
*/
setHelperParentPost = function( collection, postId ) {
@@ -590,6 +609,7 @@
* Accepts an array of tag slugs, or a Tags collection.
*
* @param {Array|Backbone.Collection} tags The tags to set on the post.
+ * @return {void|boolean} False if the tags parameter is a string, otherwise void.
*
*/
setTags: function( tags ) {
@@ -636,6 +656,7 @@
* Accepts a Tags collection.
*
* @param {Array|Backbone.Collection} tags The tags to set on the post.
+ * @return {void} No return value.
*
*/
setTagsWithCollection: function( tags ) {
@@ -674,7 +695,7 @@
* Accepts an array of category slugs, or a Categories collection.
*
* @param {Array|Backbone.Collection} categories The categories to set on the post.
- *
+ * @return {void|boolean} False if the categories parameter is a string, otherwise void.
*/
setCategories: function( categories ) {
var allCategories, newCategory,
@@ -721,7 +742,7 @@
* Accepts Categories collection.
*
* @param {Array|Backbone.Collection} categories The categories to set on the post.
- *
+ * @return {void} No return value.
*/
setCategoriesWithCollection: function( categories ) {
@@ -834,9 +855,9 @@
/**
* Set nonce header before every Backbone sync.
*
- * @param {string} method.
- * @param {Backbone.Model} model.
- * @param {{beforeSend}, *} options.
+ * @param {string} method The CRUD method ("create", "read", "update", or "delete") to be performed.
+ * @param {Backbone.Model} model The model to be synced.
+ * @param {{beforeSend}, *} options Additional options for the sync.
* @return {*}.
*/
sync: function( method, model, options ) {
@@ -888,6 +909,9 @@
/**
* Save is only allowed when the PUT OR POST methods are available for the endpoint.
+ * @param {Object} attrs The attributes to save.
+ * @param {Object} options The options for the save operation.
+ * @return {boolean} True if the save was executed, false if not allowed.
*/
save: function( attrs, options ) {
@@ -905,6 +929,8 @@
/**
* Delete is only allowed when the DELETE method is available for the endpoint.
+ * @param {Object} [options] The options for the delete operation.
+ * @return {boolean} True if the delete was executed, false if not allowed.
*/
destroy: function( options ) {
@@ -967,6 +993,8 @@
/**
* Setup default state.
+ * @param {Backbone.Model[]} models The initial array of models.
+ * @param {Object} [options] The options for the collection.
*/
initialize: function( models, options ) {
this.state = {
@@ -987,9 +1015,9 @@
*
* Set nonce header before every Backbone sync.
*
- * @param {string} method.
- * @param {Backbone.Model} model.
- * @param {{success}, *} options.
+ * @param {string} method The CRUD method ("create", "read", "update", or "delete") to be performed.
+ * @param {Backbone.Model} model The model to be synced.
+ * @param {{success}, *} options Additional options for the sync.
* @return {*}.
*/
sync: function( method, model, options ) {
@@ -1064,7 +1092,7 @@
/**
* Fetches the next page of objects if a new page exists.
*
- * @param {data: {page}} options.
+ * @param {data: {page}} options An object containing the page number to fetch. If not provided, the next page will be fetched.
* @return {*}.
*/
more: function( options ) {
@@ -1091,7 +1119,7 @@
/**
* Returns true if there are more pages of objects available.
*
- * @return {null|boolean}
+ * @return {null|boolean} Returns null if the current page, total pages, or total objects are unknown. Otherwise returns true if there are more pages available.
*/
hasMore: function() {
if ( null === this.state.totalPages ||
@@ -1499,10 +1527,11 @@
* Initialize the wp-api, optionally passing the API root.
*
* @param {Object} [args]
- * @param {string} [args.nonce] The nonce. Optional, defaults to wpApiSettings.nonce.
- * @param {string} [args.apiRoot] The api root. Optional, defaults to wpApiSettings.root.
+ * @param {string} [args.nonce] The nonce. Optional, defaults to wpApiSettings.nonce.
+ * @param {string} [args.apiRoot] The api root. Optional, defaults to wpApiSettings.root.
* @param {string} [args.versionString] The version string. Optional, defaults to wpApiSettings.root.
- * @param {Object} [args.schema] The schema. Optional, will be fetched from API if not provided.
+ * @param {Object} [args.schema] The schema. Optional, will be fetched from API if not provided.
+ * @return {Promise} A promise that resolves with the endpoint once it is ready.
*/
wp.api.init = function( args ) {
var endpoint, attributes = {}, deferred, promise;
diff --git a/src/js/_enqueues/wp/autosave.js b/src/js/_enqueues/wp/autosave.js
index 9f46c3161483e..35d7a055ed98e 100644
--- a/src/js/_enqueues/wp/autosave.js
+++ b/src/js/_enqueues/wp/autosave.js
@@ -13,8 +13,8 @@ window.autosave = function() {
*
* @since 3.9.0
*
- * @param {jQuery} $ jQuery object.
- * @param {window} The window object.
+ * @param {JQueryStatic} $ The jQuery object.
+ * @param {Object} window The window object.
*
*/
( function( $, window ) {
@@ -243,6 +243,7 @@ window.autosave = function() {
* Sets the storage for this blog. Confirms that the data was saved
* successfully.
*
+ * @param {Object} stored_obj The storage object to set.
* @since 3.9.0
*
* @return {boolean} True if the data was saved successfully, false if it wasn't saved.
diff --git a/src/js/_enqueues/wp/code-editor.js b/src/js/_enqueues/wp/code-editor.js
index ed8be9d6a5580..74276d6438011 100644
--- a/src/js/_enqueues/wp/code-editor.js
+++ b/src/js/_enqueues/wp/code-editor.js
@@ -4,8 +4,6 @@
/* global console */
-/* eslint-env es2020 */
-
if ( 'undefined' === typeof window.wp ) {
/**
* @namespace wp
@@ -20,7 +18,7 @@ if ( 'undefined' === typeof window.wp.codeEditor ) {
}
/**
- * @typedef {object} CodeMirrorState
+ * @typedef {Object} CodeMirrorState
* @property {boolean} [completionActive] - Whether completion is active.
* @property {boolean} [focused] - Whether the editor is focused.
*/
@@ -35,7 +33,7 @@ if ( 'undefined' === typeof window.wp.codeEditor ) {
*/
/**
- * @typedef {object} LintAnnotation
+ * @typedef {Object} LintAnnotation
* @property {string} message - Message.
* @property {'error'|'warning'} severity - Severity.
* @property {import('codemirror').Position} from - From position.
@@ -43,8 +41,8 @@ if ( 'undefined' === typeof window.wp.codeEditor ) {
*/
/**
- * @typedef {object} CodeMirrorTokenState
- * @property {object} [htmlState] - HTML state.
+ * @typedef {Object} CodeMirrorTokenState
+ * @property {Object} [htmlState] - HTML state.
* @property {string} [htmlState.tagName] - Tag name.
* @property {CodeMirrorTokenState} [curState] - Current state.
*/
@@ -60,7 +58,7 @@ if ( 'undefined' === typeof window.wp.codeEditor ) {
*/
/**
- * @typedef {object} CSSLintRules
+ * @typedef {Object} CSSLintRules
* @property {boolean} [errors] - Errors.
* @property {boolean} [box-model] - Box model rules.
* @property {boolean} [display-property-grouping] - Display property grouping rules.
@@ -70,7 +68,7 @@ if ( 'undefined' === typeof window.wp.codeEditor ) {
*/
/**
- * @typedef {object} JSHintRules
+ * @typedef {Object} JSHintRules
* @property {number} [esversion] - ECMAScript version.
* @property {boolean} [module] - Whether to use modules.
* @property {boolean} [boss] - Whether to allow assignments in control expressions.
@@ -89,7 +87,7 @@ if ( 'undefined' === typeof window.wp.codeEditor ) {
*/
/**
- * @typedef {object} HTMLHintRules
+ * @typedef {Object} HTMLHintRules
* @property {boolean} [tagname-lowercase] - Tag name lowercase rules.
* @property {boolean} [attr-lowercase] - Attribute lowercase rules.
* @property {boolean} [attr-value-double-quotes] - Attribute value double quotes rules.
@@ -109,7 +107,7 @@ if ( 'undefined' === typeof window.wp.codeEditor ) {
/**
* Settings for the code editor.
*
- * @typedef {object} CodeEditorSettings
+ * @typedef {Object} CodeEditorSettings
*
* @property {CodeMirrorSettings} [codemirror] - CodeMirror settings.
* @property {CSSLintRules} [csslint] - CSSLint rules.
@@ -127,20 +125,20 @@ if ( 'undefined' === typeof window.wp.codeEditor ) {
*/
/**
- * @typedef {object} CodeEditorInstance
+ * @typedef {Object} CodeEditorInstance
* @property {CodeEditorSettings} settings - The code editor settings.
* @property {CodeMirrorEditor} codemirror - The CodeMirror instance.
* @property {() => void} updateErrorNotice - Force update the error notice.
*/
/**
- * @typedef {object} WpCodeEditor
+ * @typedef {Object} WpCodeEditor
* @property {CodeEditorSettings} defaultSettings - Default settings.
* @property {(textarea: string|JQuery|Element, settings?: CodeEditorSettings) => CodeEditorInstance} initialize - Initialize.
*/
/**
- * @param {JQueryStatic} $ - jQuery.
+ * @param {JQueryStatic} $ The jQuery object.
* @param {Object & {
* codeEditor: WpCodeEditor,
* CodeMirror: typeof import('codemirror'),
@@ -173,7 +171,7 @@ if ( 'undefined' === typeof window.wp.codeEditor ) {
*
* @return {LintingController} Linting controller.
*/
- function configureLinting( settings ) { // eslint-disable-line complexity
+ function configureLinting( settings ) {
/** @type {LintAnnotation[]} */
let currentErrorAnnotations = [];
@@ -198,7 +196,7 @@ if ( 'undefined' === typeof window.wp.codeEditor ) {
*
* @return {CombinedLintOptions|false} Lint options.
*/
- function getLintOptions() { // eslint-disable-line complexity
+ function getLintOptions() {
/** @type {CombinedLintOptions | boolean} */
let options = settings.codemirror?.lint ?? false;
@@ -397,7 +395,7 @@ if ( 'undefined' === typeof window.wp.codeEditor ) {
}
/**
- * @typedef {object} LintingController
+ * @typedef {Object} LintingController
* @property {() => CombinedLintOptions|false} getLintOptions - Get lint options.
* @property {(editor: CodeMirrorEditor) => void} init - Initialize.
* @property {(editor: import('codemirror').Editor) => void} updateErrorNotice - Update error notice.
diff --git a/src/js/_enqueues/wp/custom-header.js b/src/js/_enqueues/wp/custom-header.js
index ae43f56174f23..1771ce7505544 100644
--- a/src/js/_enqueues/wp/custom-header.js
+++ b/src/js/_enqueues/wp/custom-header.js
@@ -76,7 +76,7 @@
*
* Themes and plugins can override this method to change the criteria.
*
- * @return {boolean}
+ * @return {boolean} True if the environment supports video, false otherwise.
*/
supportsVideo: function() {
// Don't load video on small screens. @todo Consider bandwidth and other factors.
@@ -163,7 +163,7 @@
* Whether the video is paused.
*
* @abstract
- * @return {boolean}
+ * @return {boolean} True if the video is paused, false otherwise.
*/
isPaused: function() {},
@@ -217,8 +217,7 @@
* Whether the handler can process a video.
*
* @abstract
- * @param {Object} settings Video settings.
- * @return {boolean}
+ * @return {boolean} True if the handler can process a video, false otherwise. Default is false.
*/
test: function() {
return false;
@@ -240,7 +239,7 @@
* @memberOf wp
*
* @param {Object} protoProps Properties to apply to the prototype.
- * @return CustomHandler The subclass.
+ * @return {Function} Custom handler constructor.
*/
BaseHandler.extend = function( protoProps ) {
var prop;
@@ -272,7 +271,7 @@
* Whether the native handler supports a video.
*
* @param {Object} settings Video settings.
- * @return {boolean}
+ * @return {boolean} True if the native handler supports a video, false otherwise.
*/
test: function( settings ) {
var video = document.createElement( 'video' );
@@ -314,7 +313,7 @@
/**
* Whether the video is paused.
*
- * @return {boolean}
+ * @return {boolean} True if the video is paused, false otherwise.
*/
isPaused: function() {
return this.video.paused;
@@ -347,7 +346,7 @@
* Whether the handler supports a video.
*
* @param {Object} settings Video settings.
- * @return {boolean}
+ * @return {boolean} True if the handler supports a video, false otherwise.
*/
test: function( settings ) {
return 'video/x-youtube' === settings.mimeType;
@@ -423,7 +422,7 @@
/**
* Whether the video is paused.
*
- * @return {boolean}
+ * @return {boolean} True if the video is paused, false otherwise.
*/
isPaused: function() {
return YT.PlayerState.PAUSED === this.player.getPlayerState();
diff --git a/src/js/_enqueues/wp/dashboard.js b/src/js/_enqueues/wp/dashboard.js
index 0c92f1e1b3e47..31c9cd7cb1547 100644
--- a/src/js/_enqueues/wp/dashboard.js
+++ b/src/js/_enqueues/wp/dashboard.js
@@ -633,10 +633,10 @@ jQuery( function( $ ) {
*
* @since 5.5.2
*
- * @param {Array} rawEvents The events that should have dynamic fields added to them.
- * @param {string} timeFormat A time format acceptable by `wp.date.dateI18n()`.
+ * @param {Object[]} rawEvents The events that should have dynamic fields added to them.
+ * @param {string} timeFormat A time format acceptable by `wp.date.dateI18n()`.
*
- * @returns {Array}
+ * @return {Object[]} The events with dynamic fields added to them.
*/
populateDynamicEventFields: function( rawEvents, timeFormat ) {
// Clone the parameter to avoid mutating it, so that this can remain a pure function.
@@ -668,9 +668,9 @@ jQuery( function( $ ) {
*
* @since 5.5.2
*
- * @param startTimestamp
+ * @param {number} startTimestamp The start timestamp of the event.
*
- * @returns {string|number}
+ * @return {string|number} A time zone string like `America/Chicago`, or a number representing the offset from UTC in minutes.
*/
getTimeZone: function( startTimestamp ) {
/*
@@ -705,7 +705,7 @@ jQuery( function( $ ) {
*
* @param {number} startTimestamp
*
- * @returns {number}
+ * @return {number} The offset from UTC in minutes, with the sign flipped to be more intuitive.
*/
getFlippedTimeZoneOffset: function( startTimestamp ) {
return new Date( startTimestamp ).getTimezoneOffset() * -1;
@@ -718,7 +718,7 @@ jQuery( function( $ ) {
*
* @param {number} startTimestamp
*
- * @returns {string}
+ * @return {string} A short time zone name, like `PST`, or a string like `GMT+5` if the abbreviation can't be determined.
*/
getTimeZoneAbbreviation: function( startTimestamp ) {
var timeZoneAbbreviation,
@@ -758,11 +758,11 @@ jQuery( function( $ ) {
*
* @since 5.5.2
*
- * @param {int} startDate The Unix timestamp in milliseconds when the event starts.
- * @param {int} endDate The Unix timestamp in milliseconds when the event ends.
- * @param {string} timeZone A time zone string or offset which is parsable by `wp.date.i18n()`.
+ * @param {number} startDate The Unix timestamp in milliseconds when the event starts.
+ * @param {number} endDate The Unix timestamp in milliseconds when the event ends.
+ * @param {string} timeZone A time zone string or offset which is parsable by `wp.date.i18n()`.
*
- * @returns {string}
+ * @return {string} A formatted date string, like `Mon, Jan 1, 2024` or `Jan 1–3, 2024`.
*/
getFormattedDate: function( startDate, endDate, timeZone ) {
var formattedDate;
@@ -834,7 +834,7 @@ jQuery( function( $ ) {
* @since 4.8.0
* @deprecated 5.6.0
*
- * @type {object}
+ * @type {Object}
*/
window.communityEventsData.l10n = window.communityEventsData.l10n || {
enter_closest_city: '',
diff --git a/src/js/_enqueues/wp/editor/base.js b/src/js/_enqueues/wp/editor/base.js
index b5f1731d4afc5..c2c264e3f8045 100644
--- a/src/js/_enqueues/wp/editor/base.js
+++ b/src/js/_enqueues/wp/editor/base.js
@@ -11,6 +11,7 @@ window.wp = window.wp || {};
* Utility functions for the editor.
*
* @since 2.5.0
+ * @return {Object} The editor utility functions.
*/
function SwitchEditors() {
var tinymce, $$,
@@ -239,8 +240,8 @@ window.wp = window.wp || {};
* @param {string} content The text content to check against.
* @param {number} cursorPosition The cursor position to check.
*
- * @return {(undefined|Object)} Undefined if the cursor is not wrapped in a shortcode tag.
- * Information about the wrapping shortcode tag if it's wrapped in one.
+ * @return {void|Object} Undefined if the cursor is not wrapped in a shortcode tag.
+ * Information about the wrapping shortcode tag if it's wrapped in one.
*/
function getShortcodeWrapperInfo( content, cursorPosition ) {
var contentShortcodes = getShortCodePositionsInText( content );
@@ -258,6 +259,7 @@ window.wp = window.wp || {};
* Gets a list of unique shortcodes or shortcode-lookalikes in the content.
*
* @param {string} content The content we want to scan for shortcodes.
+ * @return {string[]} An array of unique shortcodes found in the content.
*/
function getShortcodesInText( content ) {
var shortcodes = content.match( /\[+([\w_-])+/g ),
@@ -290,7 +292,8 @@ window.wp = window.wp || {};
* The information can also be used in other cases when we need to lookup shortcode data,
* as it's already structured!
*
- * @param {string} content The content we want to scan for shortcodes
+ * @param {string} content The content we want to scan for shortcodes.
+ * @return {Object[]} An array of objects with information about the shortcodes found in the content.
*/
function getShortCodePositionsInText( content ) {
var allShortcodes = getShortcodesInText( content ), shortcodeInfo;
@@ -362,6 +365,7 @@ window.wp = window.wp || {};
*
* @param {Object} domLib DOM library instance.
* @param {string} content The content to insert into the cursor marker element.
+ * @return {Object} The cursor marker element.
*/
function getCursorMarkerSpan( domLib, content ) {
return domLib( '' ).css( {
@@ -385,7 +389,7 @@ window.wp = window.wp || {};
* @param {string} content Textarea content that the cursors are in
* @param {{cursorStart: number, cursorEnd: number}} cursorPositions Cursor start and end positions
*
- * @return {{cursorStart: number, cursorEnd: number}}
+ * @return {{cursorStart: number, cursorEnd: number}} Adjusted cursor positions with `cursorStart` and `cursorEnd` properties.
*/
function adjustTextAreaSelectionCursors( content, cursorPositions ) {
var voidElements = [
@@ -649,7 +653,7 @@ window.wp = window.wp || {};
* and why this solution was chosen.
*
* @param {Object} editor The editor where we must find the selection.
- * @return {(null|Object)} The selection range position in the editor.
+ * @return {void|Object} The selection range position in the editor.
*/
function findBookmarkedPosition( editor ) {
// Get the TinyMCE `window` reference, since we need to access the raw selection.
@@ -1381,7 +1385,7 @@ window.wp = window.wp || {};
* @since 4.8.0
*
* @param {string} id The HTML id of the editor textarea.
- * @return The editor content.
+ * @return {void|string} The editor content.
*/
wp.editor.getContent = function( id ) {
var editor;
diff --git a/src/js/_enqueues/wp/editor/dfw.js b/src/js/_enqueues/wp/editor/dfw.js
index 04b001e1c8059..37105aecd8bc9 100644
--- a/src/js/_enqueues/wp/editor/dfw.js
+++ b/src/js/_enqueues/wp/editor/dfw.js
@@ -2,6 +2,11 @@
* @output wp-admin/js/editor-expand.js
*/
+/**
+ * @param {Window} window The global window object.
+ * @param {JQueryStatic} $ The jQuery object.
+ * @param {undefined} undefined The undefined value.
+ */
( function( window, $, undefined ) {
'use strict';
@@ -167,7 +172,7 @@
* @since 4.0.0
*
* @param {event} event The TinyMCE editor init event.
- * @param {object} editor The editor to bind the vents on.
+ * @param {Object} editor The editor to bind the vents on.
*
* @return {void}
*/
@@ -785,7 +790,7 @@
*
* @since 4.0.0
*
- * @param {function} callback The function to run in the timeout.
+ * @param {Function} callback The function to run in the timeout.
*
* @return {void}
*/
@@ -1160,7 +1165,7 @@
*
* @since 4.1.0
*
- * @param event The event that triggers this function.
+ * @param {Event} event The event that triggers this function.
*
* @return {void}
*/
@@ -1299,7 +1304,7 @@
*
* @since 4.1.0
*
- * @param event The event that triggers this function.
+ * @param {Event} event The event that triggers this function.
*
* @return {void}
*/
@@ -1461,7 +1466,7 @@
* @since 4.1.0
*
* @param {event} event The TinyMCE editor setup event.
- * @param {object} editor The editor to add the button to.
+ * @param {Object} editor The editor to add the button to.
*
* @return {void}
*/
@@ -1510,7 +1515,7 @@
* @since 4.1.0
*
* @param {event} event The TinyMCE editor init event.
- * @param {object} editor The editor to bind events on.
+ * @param {Object} editor The editor to bind events on.
*
* @return {void}
*/
@@ -1567,7 +1572,7 @@
* @since 4.1.0
*
* @param {event} event The quicktags init event.
- * @param {object} editor The editor to bind events on.
+ * @param {Object} editor The editor to bind events on.
*
* @return {void}
*/
diff --git a/src/js/_enqueues/wp/embed.js b/src/js/_enqueues/wp/embed.js
index 315e573f5cb82..724daa3283e93 100644
--- a/src/js/_enqueues/wp/embed.js
+++ b/src/js/_enqueues/wp/embed.js
@@ -1,6 +1,8 @@
/**
* WordPress inline HTML embed
*
+ * @param {Window} window The global window object.
+ * @param {Document} document The global document object.
* @since 4.4.0
* @output wp-includes/js/wp-embed.js
*
@@ -28,7 +30,7 @@
/**
* Receive embed message.
*
- * @param {MessageEvent} e
+ * @param {MessageEvent} e The message event.
*/
window.wp.receiveEmbedMessage = function( e ) {
var data = e.data;
@@ -90,7 +92,7 @@
i, source, secret;
for ( i = 0; i < iframes.length; i++ ) {
- /** @var {IframeElement} */
+ /** @type {HTMLIFrameElement}} */
source = iframes[ i ];
secret = source.getAttribute( 'data-secret' );
diff --git a/src/js/_enqueues/wp/emoji.js b/src/js/_enqueues/wp/emoji.js
index 05582de672662..1c134e2dfef85 100644
--- a/src/js/_enqueues/wp/emoji.js
+++ b/src/js/_enqueues/wp/emoji.js
@@ -2,6 +2,8 @@
* wp-emoji.js is used to replace emoji with images in browsers when the browser
* doesn't support emoji natively.
*
+ * @param {Window} window The global window object.
+ * @param {Object} settings The settings object.
* @output wp-includes/js/wp-emoji.js
*/
diff --git a/src/js/_enqueues/wp/heartbeat.js b/src/js/_enqueues/wp/heartbeat.js
index 65635177d9f66..670d8d047a2ff 100644
--- a/src/js/_enqueues/wp/heartbeat.js
+++ b/src/js/_enqueues/wp/heartbeat.js
@@ -27,6 +27,11 @@
* @output wp-includes/js/heartbeat.js
*/
+/**
+ * @param {JQueryStatic} $ The jQuery object.
+ * @param {Window} window The global window object.
+ * @param {undefined} undefined The undefined value.
+ */
( function( $, window, undefined ) {
/**
@@ -35,7 +40,7 @@
* @since 3.6.0
*
* @return {Object} An instance of the Heartbeat class.
- * @constructor
+ * @class
*/
var Heartbeat = function() {
var $document = $(document),
@@ -281,6 +286,7 @@
* @since 3.6.0
* @access private
*
+ * @param {HTMLIFrameElement} frame The iframe element to check.
* @return {boolean} Returns whether or not the iframe is from the same origin.
*/
function isLocalFrame( frame ) {
@@ -824,7 +830,7 @@
*
* @param {string} handle The handle for the data.
*
- * @return {boolean} True if the data is queued with this handle.
+ * @return {void|boolean} True if the data is queued with this handle.
*/
function isQueued( handle ) {
if ( handle ) {
diff --git a/src/js/_enqueues/wp/mce-view.js b/src/js/_enqueues/wp/mce-view.js
index 863803f614816..01dbaedf1f122 100644
--- a/src/js/_enqueues/wp/mce-view.js
+++ b/src/js/_enqueues/wp/mce-view.js
@@ -88,8 +88,8 @@
* replacing any matches with markers,
* and creates a new instance for every match.
*
- * @param {string} content The string to scan.
- * @param {tinymce.Editor} editor The editor.
+ * @param {string} content The string to scan.
+ * @param {tinymce.Editor} editor The editor.
*
* @return {string} The string with markers.
*/
@@ -190,7 +190,7 @@
/**
* Get a view instance.
*
- * @param {(string|HTMLElement)} object The textual representation of the view or the view node.
+ * @param {string|HTMLElement} object The textual representation of the view or the view node.
*
* @return {wp.mce.View} The view instance or undefined.
*/
@@ -296,7 +296,7 @@
/**
* Whether or not to display a loader.
*
- * @type {Boolean}
+ * @type {boolean}
*/
loader: true,
@@ -308,7 +308,7 @@
/**
* Returns the content to render in the view node.
*
- * @return {*}
+ * @return {*} The content.
*/
getContent: function() {
return this.content;
@@ -675,6 +675,8 @@
/**
* Sets a loader for all view nodes tied to this view instance.
+ *
+ * @param {string} dashicon The dashicon ID. Optional.
*/
setLoader: function( dashicon ) {
this.setContent(
@@ -705,7 +707,7 @@
*
* @param {string} content The string to scan.
*
- * @return {Object}
+ * @return {void|Object} An object with the match index, content and options, or undefined if no match was found.
*/
match: function( content ) {
var match = shortcode.next( this.type, content );
diff --git a/src/js/_enqueues/wp/media/audiovideo.js b/src/js/_enqueues/wp/media/audiovideo.js
index f0127cc507119..485a1699726bf 100644
--- a/src/js/_enqueues/wp/media/audiovideo.js
+++ b/src/js/_enqueues/wp/media/audiovideo.js
@@ -44,6 +44,7 @@ wp.media.mixin = {
*
* @since 4.2.0
*
+ * @param {Object} t The MediaElement player object.
* @return {void}
*/
removePlayer: function(t) {
diff --git a/src/js/_enqueues/wp/media/editor.js b/src/js/_enqueues/wp/media/editor.js
index 1097bca966fdb..2cb6277f7533b 100644
--- a/src/js/_enqueues/wp/media/editor.js
+++ b/src/js/_enqueues/wp/media/editor.js
@@ -206,7 +206,7 @@
*
* @param {Object} props Attachment details (align, link, size, etc).
* @param {Object} attachment The attachment object, media version of Post.
- * @return {string}
+ * @return {string} The image markup.
*/
image: function( props, attachment ) {
var img = {},
@@ -415,7 +415,7 @@
* the media items belonging to a collection.
* The query[ this.tag ] property is a Backbone.Model
* containing the 'props' for the collection.
- * @return {wp.shortcode}
+ * @return {wp.shortcode} A wp.shortcode instance representing the collection.
*/
shortcode: function( attachments ) {
var props = attachments.props.toJSON(),
@@ -486,7 +486,7 @@
*
* @this wp.media.{prop}
*
- * @return {wp.media.view.MediaFrame.Select} A media workflow.
+ * @return {void|wp.media.view.MediaFrame.Select} A media workflow.
*/
edit: function( content ) {
var shortcode = wp.shortcode.next( this.tag, content ),
@@ -606,7 +606,7 @@
/**
* Get the featured image post ID
*
- * @return {wp.media.view.settings.post.featuredImageId|number}
+ * @return {wp.media.view.settings.post.featuredImageId|number} The post ID of the featured image, or -1 if none is set.
*/
get: function() {
return wp.media.view.settings.post.featuredImageId;
@@ -727,7 +727,8 @@
/**
* Send content to the editor
*
- * @param {string} html Content to send to the editor
+ * @param {string} html Content to send to the editor.
+ * @return {void}
*/
insert: function( html ) {
var editor, wpActiveEditor,
@@ -889,7 +890,7 @@
*
* @param {string} [id=''] A slug used to identify the workflow.
*
- * @return {wpActiveEditor|string|tinymce.activeEditor.id}
+ * @return {wpActiveEditor|string|tinymce.activeEditor.id} The current workflow id.
*/
id: function( id ) {
if ( id ) {
@@ -940,7 +941,7 @@
*
* @param {Object} props Attachment details (align, link, size, etc).
* @param {Object} attachment The attachment object, media version of Post.
- * @return {Promise}
+ * @return {Promise} A promise that resolves when the attachment has been sent to the editor.
*/
attachment: function( props, attachment ) {
var caption = attachment.caption,
@@ -995,7 +996,7 @@
* Called when 'Insert From URL' source is not an image. Example: YouTube url.
*
* @param {Object} embed
- * @return {Promise}
+ * @return {Promise} A promise that resolves when the link has been sent to the editor.
*/
link: function( embed ) {
return wp.media.post( 'send-link-to-editor', {
@@ -1008,14 +1009,14 @@
}
},
/**
- * Open a workflow
+ * Opens a workflow.
*
* @param {string} [id=undefined] Optional. A slug used to identify the workflow.
* @param {Object} [options={}]
*
* @this wp.media.editor
*
- * @return {wp.media.view.MediaFrame}
+ * @return {wp.media.view.MediaFrame} A media workflow.
*/
open: function( id, options ) {
var workflow;
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/revisions.js b/src/js/_enqueues/wp/revisions.js
index b0c555e934361..3efb3dcb7ac5d 100644
--- a/src/js/_enqueues/wp/revisions.js
+++ b/src/js/_enqueues/wp/revisions.js
@@ -368,8 +368,8 @@ window.wp = window.wp || {};
*
* @see wp.revisions.view.Frame
*
- * @param {object} attributes Model attributes - none are required.
- * @param {object} options Options for the model.
+ * @param {Object} attributes Model attributes - none are required.
+ * @param {Object} options Options for the model.
* @param {revisions.model.Revisions} options.revisions A collection of revisions.
*/
revisions.model.FrameState = Backbone.Model.extend({
@@ -533,7 +533,7 @@ window.wp = window.wp || {};
*
* Top level frame that orchestrates the revisions experience.
*
- * @param {object} options The options hash for the view.
+ * @param {Object} options The options hash for the view.
* @param {revisions.model.FrameState} options.model The frame state model.
*/
revisions.view.Frame = wp.Backbone.View.extend({
diff --git a/src/js/_enqueues/wp/sanitize.js b/src/js/_enqueues/wp/sanitize.js
index c0b6b0bed9494..d67bc0b77ad45 100644
--- a/src/js/_enqueues/wp/sanitize.js
+++ b/src/js/_enqueues/wp/sanitize.js
@@ -2,8 +2,6 @@
* @output wp-includes/js/wp-sanitize.js
*/
-/* eslint-env es6 */
-
( function () {
window.wp = window.wp || {};
diff --git a/src/js/_enqueues/wp/theme-plugin-editor.js b/src/js/_enqueues/wp/theme-plugin-editor.js
index 7bcff376e9ff2..88c985be42012 100644
--- a/src/js/_enqueues/wp/theme-plugin-editor.js
+++ b/src/js/_enqueues/wp/theme-plugin-editor.js
@@ -2,14 +2,15 @@
* @output wp-admin/js/theme-plugin-editor.js
*/
-/* eslint-env es2020 */
-
/* eslint no-magic-numbers: ["error", { "ignore": [-1, 0, 1, 9, 1000] }] */
if ( ! window.wp ) {
window.wp = {};
}
+/**
+ * @param {JQueryStatic} $ The jQuery object.
+ */
wp.themePluginEditor = (function( $ ) {
'use strict';
var component, TreeLinks,
@@ -476,10 +477,6 @@ wp.themePluginEditor = (function( $ ) {
} );
};
- /* jshint ignore:start */
- /* jscs:disable */
- /* eslint-disable */
-
/**
* Creates a new TreeitemLink.
*
@@ -503,9 +500,9 @@ wp.themePluginEditor = (function( $ ) {
*/
/**
- * @constructor
+ * @class
*
- * @desc
+ * @description
* Treeitem object for representing the state and user interactions for a
* treeItem widget
*
@@ -601,10 +598,8 @@ wp.themePluginEditor = (function( $ ) {
/* EVENT HANDLERS */
TreeitemLink.prototype.handleKeydown = function (event) {
- var tgt = event.currentTarget,
- flag = false,
- _char = event.key,
- clickEvent;
+ var flag = false,
+ _char = event.key;
function isPrintableCharacter(str) {
return str.length === 1 && str.match(/\S/);
@@ -736,7 +731,7 @@ wp.themePluginEditor = (function( $ ) {
}
};
- TreeitemLink.prototype.handleFocus = function (event) {
+ TreeitemLink.prototype.handleFocus = function () {
var node = this.domNode;
if (this.isExpandable) {
node = node.firstElementChild;
@@ -744,7 +739,7 @@ wp.themePluginEditor = (function( $ ) {
node.classList.add('focus');
};
- TreeitemLink.prototype.handleBlur = function (event) {
+ TreeitemLink.prototype.handleBlur = function () {
var node = this.domNode;
if (this.isExpandable) {
node = node.firstElementChild;
@@ -1022,10 +1017,6 @@ wp.themePluginEditor = (function( $ ) {
return TreeLinks;
})();
- /* jshint ignore:end */
- /* jscs:enable */
- /* eslint-enable */
-
return component;
})( jQuery );
@@ -1035,7 +1026,7 @@ wp.themePluginEditor = (function( $ ) {
* @since 4.9.0
* @deprecated 5.5.0
*
- * @type {object}
+ * @type {Object}
*/
wp.themePluginEditor.l10n = wp.themePluginEditor.l10n || {
saveAlert: '',
diff --git a/src/js/_enqueues/wp/theme.js b/src/js/_enqueues/wp/theme.js
index cfcea1fcc58b7..2249495ea4d1b 100644
--- a/src/js/_enqueues/wp/theme.js
+++ b/src/js/_enqueues/wp/theme.js
@@ -208,7 +208,7 @@ themes.Collection = Backbone.Collection.extend({
/**
* Performs a search within the collection.
*
- * @uses RegExp
+ * @param {string} term The search term.
*/
search: function( term ) {
var match, results, haystack, name, description, author;
@@ -1969,7 +1969,7 @@ themes.view.Installer = themes.view.Appearance.extend({
/**
* Clears all the checked filters.
*
- * @uses filtersChecked()
+ * @param {Event} event The click event.
*/
clearFilters: function( event ) {
var items = $( '.filter-group' ).find( ':checkbox' ),
diff --git a/src/js/_enqueues/wp/updates.js b/src/js/_enqueues/wp/updates.js
index ef4b47e66093e..63235ef71712c 100644
--- a/src/js/_enqueues/wp/updates.js
+++ b/src/js/_enqueues/wp/updates.js
@@ -8,26 +8,26 @@
/* global pagenow, _wpThemeSettings */
/**
- * @param {jQuery} $ jQuery object.
- * @param {object} wp WP object.
- * @param {object} settings WP Updates settings.
- * @param {string} settings.ajax_nonce Ajax nonce.
- * @param {object=} settings.plugins Base names of plugins in their different states.
- * @param {Array} settings.plugins.all Base names of all plugins.
- * @param {Array} settings.plugins.active Base names of active plugins.
- * @param {Array} settings.plugins.inactive Base names of inactive plugins.
- * @param {Array} settings.plugins.upgrade Base names of plugins with updates available.
- * @param {Array} settings.plugins.recently_activated Base names of recently activated plugins.
- * @param {Array} settings.plugins['auto-update-enabled'] Base names of plugins set to auto-update.
- * @param {Array} settings.plugins['auto-update-disabled'] Base names of plugins set to not auto-update.
- * @param {object=} settings.themes Slugs of themes in their different states.
- * @param {Array} settings.themes.all Slugs of all themes.
- * @param {Array} settings.themes.upgrade Slugs of themes with updates available.
- * @param {Arrat} settings.themes.disabled Slugs of disabled themes.
- * @param {Array} settings.themes['auto-update-enabled'] Slugs of themes set to auto-update.
- * @param {Array} settings.themes['auto-update-disabled'] Slugs of themes set to not auto-update.
- * @param {object=} settings.totals Combined information for available update counts.
- * @param {number} settings.totals.count Holds the amount of available updates.
+ * @param {JQueryStatic} $ The jQuery object.
+ * @param {Object} wp WP object.
+ * @param {Object} settings WP Updates settings.
+ * @param {string} settings.ajax_nonce Ajax nonce.
+ * @param {Object} settings.plugins Base names of plugins in their different states.
+ * @param {Array} settings.plugins.all Base names of all plugins.
+ * @param {Array} settings.plugins.active Base names of active plugins.
+ * @param {Array} settings.plugins.inactive Base names of inactive plugins.
+ * @param {Array} settings.plugins.upgrade Base names of plugins with updates available.
+ * @param {Array} settings.plugins.recently_activated Base names of recently activated plugins.
+ * @param {Array} settings.plugins['auto-update-enabled'] Base names of plugins set to auto-update.
+ * @param {Array} settings.plugins['auto-update-disabled'] Base names of plugins set to not auto-update.
+ * @param {Object} settings.themes Slugs of themes in their different states.
+ * @param {Array} settings.themes.all Slugs of all themes.
+ * @param {Array} settings.themes.upgrade Slugs of themes with updates available.
+ * @param {Array} settings.themes.disabled Slugs of disabled themes.
+ * @param {Array} settings.themes['auto-update-enabled'] Slugs of themes set to auto-update.
+ * @param {Array} settings.themes['auto-update-disabled'] Slugs of themes set to not auto-update.
+ * @param {Object} settings.totals Combined information for available update counts.
+ * @param {number} settings.totals.count Holds the amount of available updates.
*/
(function( $, wp, settings ) {
var $document = $( document ),
@@ -54,7 +54,7 @@
* @since 4.2.0
* @deprecated 5.5.0
*
- * @type {object}
+ * @type {Object}
*/
wp.updates.l10n = {
searchResults: '',
@@ -155,7 +155,7 @@
*
* @since 4.2.0
*
- * @type {bool}
+ * @type {boolean}
*/
wp.updates.shouldRequestFilesystemCredentials = false;
@@ -166,18 +166,18 @@
* @since 4.6.0 Added `available` property to indicate whether credentials have been provided.
*
* @type {Object}
- * @property {Object} filesystemCredentials.ftp Holds FTP credentials.
- * @property {string} filesystemCredentials.ftp.host FTP host. Default empty string.
- * @property {string} filesystemCredentials.ftp.username FTP user name. Default empty string.
- * @property {string} filesystemCredentials.ftp.password FTP password. Default empty string.
- * @property {string} filesystemCredentials.ftp.connectionType Type of FTP connection. 'ssh', 'ftp', or 'ftps'.
- * Default empty string.
- * @property {Object} filesystemCredentials.ssh Holds SSH credentials.
- * @property {string} filesystemCredentials.ssh.publicKey The public key. Default empty string.
- * @property {string} filesystemCredentials.ssh.privateKey The private key. Default empty string.
- * @property {string} filesystemCredentials.fsNonce Filesystem credentials form nonce.
- * @property {bool} filesystemCredentials.available Whether filesystem credentials have been provided.
- * Default 'false'.
+ * @property {Object} filesystemCredentials.ftp Holds FTP credentials.
+ * @property {string} filesystemCredentials.ftp.host FTP host. Default empty string.
+ * @property {string} filesystemCredentials.ftp.username FTP user name. Default empty string.
+ * @property {string} filesystemCredentials.ftp.password FTP password. Default empty string.
+ * @property {string} filesystemCredentials.ftp.connectionType Type of FTP connection. 'ssh', 'ftp', or 'ftps'.
+ * Default empty string.
+ * @property {Object} filesystemCredentials.ssh Holds SSH credentials.
+ * @property {string} filesystemCredentials.ssh.publicKey The public key. Default empty string.
+ * @property {string} filesystemCredentials.ssh.privateKey The private key. Default empty string.
+ * @property {string} filesystemCredentials.fsNonce Filesystem credentials form nonce.
+ * @property {boolean} filesystemCredentials.available Whether filesystem credentials have been provided.
+ * Default 'false'.
*/
wp.updates.filesystemCredentials = {
ftp: {
@@ -200,7 +200,7 @@
* @since 4.2.0
* @since 4.6.0 More accurately named `ajaxLocked`.
*
- * @type {bool}
+ * @type {boolean}
*/
wp.updates.ajaxLocked = false;
@@ -209,7 +209,7 @@
*
* @since 4.6.0
*
- * @type {function}
+ * @type {Function}
*/
wp.updates.adminNotice = wp.template( 'wp-updates-admin-notice' );
@@ -240,14 +240,14 @@
*
* @since 4.6.0
*
- * @param {Object} data
- * @param {*=} data.selector Optional. Selector of an element to be replaced with the admin notice.
- * @param {string=} data.id Optional. Unique id that will be used as the notice's id attribute.
- * @param {string=} data.className Optional. Class names that will be used in the admin notice.
- * @param {string=} data.message Optional. The message displayed in the notice.
- * @param {number=} data.successes Optional. The amount of successful operations.
- * @param {number=} data.errors Optional. The amount of failed operations.
- * @param {Array=} data.errorMessages Optional. Error messages of failed operations.
+ * @param {Object} data
+ * @param {*} [data.selector] Optional. Selector of an element to be replaced with the admin notice.
+ * @param {string} [data.id] Optional. Unique id that will be used as the notice's id attribute.
+ * @param {string} [data.className] Optional. Class names that will be used in the admin notice.
+ * @param {string} [data.message] Optional. The message displayed in the notice.
+ * @param {number} [data.successes] Optional. The amount of successful operations.
+ * @param {number} [data.errors] Optional. The amount of failed operations.
+ * @param {Array} [data.errorMessages] Optional. Error messages of failed operations.
*
*/
wp.updates.addAdminNotice = function( data ) {
@@ -333,9 +333,9 @@
*
* @since 4.6.0
*
- * @param {Object} response
- * @param {Array=} response.debug Optional. Debug information.
- * @param {string=} response.errorCode Optional. Error code for an error that occurred.
+ * @param {Object} response
+ * @param {Array} [response.debug] Optional. Debug information.
+ * @param {string} [response.errorCode] Optional. Error code for an error that occurred.
*/
wp.updates.ajaxAlways = function( response ) {
if ( ! response.errorCode || 'unable_to_connect_to_filesystem' !== response.errorCode ) {
@@ -427,16 +427,16 @@
*
* @since 6.5.0
*
- * @param {Object} data An object of data to use for the button.
- * @param {string} data.slug The plugin's slug.
- * @param {string} data.text The text to use for the button.
- * @param {string} data.ariaLabel The value for the button's aria-label attribute. An empty string removes the attribute.
- * @param {string=} data.status Optional. An identifier for the status.
- * @param {string=} data.removeClasses Optional. A space-separated list of classes to remove from the button.
- * @param {string=} data.addClasses Optional. A space-separated list of classes to add to the button.
- * @param {string=} data.href Optional. The button's URL.
- * @param {string=} data.pluginName Optional. The plugin's name.
- * @param {string=} data.plugin Optional. The plugin file, relative to the plugins directory.
+ * @param {Object} data An object of data to use for the button.
+ * @param {string} data.slug The plugin's slug.
+ * @param {string} data.text The text to use for the button.
+ * @param {string} data.ariaLabel The value for the button's aria-label attribute. An empty string removes the attribute.
+ * @param {string} [data.status] Optional. An identifier for the status.
+ * @param {string} [data.removeClasses] Optional. A space-separated list of classes to remove from the button.
+ * @param {string} [data.addClasses] Optional. A space-separated list of classes to add to the button.
+ * @param {string} [data.href] Optional. The button's URL.
+ * @param {string} [data.pluginName] Optional. The plugin's name.
+ * @param {string} [data.plugin] Optional. The plugin file, relative to the plugins directory.
*/
wp.updates.setCardButtonStatus = function( data ) {
var target = window.parent === window ? null : window.parent;
@@ -476,11 +476,11 @@
* @since 4.2.0
* @since 4.6.0 More accurately named `updatePlugin`.
*
- * @param {Object} args Arguments.
- * @param {string} args.plugin Plugin basename.
- * @param {string} args.slug Plugin slug.
- * @param {updatePluginSuccess=} args.success Optional. Success callback. Default: wp.updates.updatePluginSuccess
- * @param {updatePluginError=} args.error Optional. Error callback. Default: wp.updates.updatePluginError
+ * @param {Object} args Arguments.
+ * @param {string} args.plugin Plugin basename.
+ * @param {string} args.slug Plugin slug.
+ * @param {updatePluginSuccess} [args.success] Optional. Success callback. Default: wp.updates.updatePluginSuccess
+ * @param {updatePluginError} [args.error] Optional. Error callback. Default: wp.updates.updatePluginError
* @return {$.promise} A jQuery promise that represents the request,
* decorated with an abort() method.
*/
@@ -619,12 +619,12 @@
* @since 4.2.0
* @since 4.6.0 More accurately named `updatePluginError`.
*
- * @param {Object} response Response from the server.
- * @param {string} response.slug Slug of the plugin to be updated.
- * @param {string} response.plugin Basename of the plugin to be updated.
- * @param {string=} response.pluginName Optional. Name of the plugin to be updated.
- * @param {string} response.errorCode Error code for the error that occurred.
- * @param {string} response.errorMessage The error that occurred.
+ * @param {Object} response Response from the server.
+ * @param {string} response.slug Slug of the plugin to be updated.
+ * @param {string} response.plugin Basename of the plugin to be updated.
+ * @param {string} response.pluginName Optional. Name of the plugin to be updated.
+ * @param {string} response.errorCode Error code for the error that occurred.
+ * @param {string} response.errorMessage The error that occurred.
*/
wp.updates.updatePluginError = function( response ) {
var $pluginRow, $card, $message, errorMessage, buttonText, ariaLabel,
@@ -736,10 +736,10 @@
*
* @since 4.6.0
*
- * @param {Object} args Arguments.
- * @param {string} args.slug Plugin identifier in the WordPress.org Plugin repository.
- * @param {installPluginSuccess=} args.success Optional. Success callback. Default: wp.updates.installPluginSuccess
- * @param {installPluginError=} args.error Optional. Error callback. Default: wp.updates.installPluginError
+ * @param {Object} args Arguments.
+ * @param {string} args.slug Plugin identifier in the WordPress.org Plugin repository.
+ * @param {installPluginSuccess} args.success Optional. Success callback. Default: wp.updates.installPluginSuccess
+ * @param {installPluginError} args.error Optional. Error callback. Default: wp.updates.installPluginError
* @return {$.promise} A jQuery promise that represents the request,
* decorated with an abort() method.
*/
@@ -851,11 +851,11 @@
*
* @since 4.6.0
*
- * @param {Object} response Response from the server.
- * @param {string} response.slug Slug of the plugin to be installed.
- * @param {string=} response.pluginName Optional. Name of the plugin to be installed.
- * @param {string} response.errorCode Error code for the error that occurred.
- * @param {string} response.errorMessage The error that occurred.
+ * @param {Object} response Response from the server.
+ * @param {string} response.slug Slug of the plugin to be installed.
+ * @param {string} response.pluginName Optional. Name of the plugin to be installed.
+ * @param {string} response.errorCode Error code for the error that occurred.
+ * @param {string} response.errorMessage The error that occurred.
*/
wp.updates.installPluginError = function( response ) {
var $card = $( '.plugin-card-' + response.slug + ', #plugin-information-footer' ),
@@ -922,10 +922,10 @@
*
* @since 6.5.0
*
- * @param {Object} args Arguments.
- * @param {string} args.slug Plugin identifier in the WordPress.org Plugin repository.
- * @param {checkPluginDependenciesSuccess=} args.success Optional. Success callback. Default: wp.updates.checkPluginDependenciesSuccess
- * @param {checkPluginDependenciesError=} args.error Optional. Error callback. Default: wp.updates.checkPluginDependenciesError
+ * @param {Object} args Arguments.
+ * @param {string} args.slug Plugin identifier in the WordPress.org Plugin repository.
+ * @param {checkPluginDependenciesSuccess} args.success Optional. Success callback. Default: wp.updates.checkPluginDependenciesSuccess
+ * @param {checkPluginDependenciesError} args.error Optional. Error callback. Default: wp.updates.checkPluginDependenciesError
* @return {$.promise} A jQuery promise that represents the request,
* decorated with an abort() method.
*/
@@ -1014,11 +1014,11 @@
*
* @since 6.5.0
*
- * @param {Object} response Response from the server.
- * @param {string} response.slug Slug of the plugin to be checked.
- * @param {string=} response.pluginName Optional. Name of the plugin to be checked.
- * @param {string} response.errorCode Error code for the error that occurred.
- * @param {string} response.errorMessage The error that occurred.
+ * @param {Object} response Response from the server.
+ * @param {string} response.slug Slug of the plugin to be checked.
+ * @param {string} response.pluginName Optional. Name of the plugin to be checked.
+ * @param {string} response.errorCode Error code for the error that occurred.
+ * @param {string} response.errorMessage The error that occurred.
*/
wp.updates.checkPluginDependenciesError = function( response ) {
var $message = $( '.plugin-card-' + response.slug + ', #plugin-information-footer' ).find( '.install-now' ),
@@ -1069,12 +1069,12 @@
*
* @since 6.5.0
*
- * @param {Object} args Arguments.
- * @param {string} args.name The name of the plugin.
- * @param {string} args.slug Plugin identifier in the WordPress.org Plugin repository.
- * @param {string} args.plugin The plugin file, relative to the plugins directory.
- * @param {activatePluginSuccess=} args.success Optional. Success callback. Default: wp.updates.activatePluginSuccess
- * @param {activatePluginError=} args.error Optional. Error callback. Default: wp.updates.activatePluginError
+ * @param {Object} args Arguments.
+ * @param {string} args.name The name of the plugin.
+ * @param {string} args.slug Plugin identifier in the WordPress.org Plugin repository.
+ * @param {string} args.plugin The plugin file, relative to the plugins directory.
+ * @param {activatePluginSuccess} args.success Optional. Success callback. Default: wp.updates.activatePluginSuccess
+ * @param {activatePluginError} args.error Optional. Error callback. Default: wp.updates.activatePluginError
* @return {$.promise} A jQuery promise that represents the request,
* decorated with an abort() method.
*/
@@ -1177,11 +1177,11 @@
*
* @since 6.5.0
*
- * @param {Object} response Response from the server.
- * @param {string} response.slug Slug of the plugin to be activated.
- * @param {string=} response.pluginName Optional. Name of the plugin to be activated.
- * @param {string} response.errorCode Error code for the error that occurred.
- * @param {string} response.errorMessage The error that occurred.
+ * @param {Object} response Response from the server.
+ * @param {string} response.slug Slug of the plugin to be activated.
+ * @param {string} response.pluginName Optional. Name of the plugin to be activated.
+ * @param {string} response.errorCode Error code for the error that occurred.
+ * @param {string} response.errorMessage The error that occurred.
*/
wp.updates.activatePluginError = function( response ) {
var $message = $( '.plugin-card-' + response.slug + ', #plugin-information-footer' ).find( '.activating-message' ),
@@ -1270,11 +1270,11 @@
*
* @since 4.6.0
*
- * @param {Object} response Response from the server.
- * @param {string} response.slug Slug of the plugin to be installed.
- * @param {string=} response.pluginName Optional. Name of the plugin to be installed.
- * @param {string} response.errorCode Error code for the error that occurred.
- * @param {string} response.errorMessage The error that occurred.
+ * @param {Object} response Response from the server.
+ * @param {string} response.slug Slug of the plugin to be installed.
+ * @param {string} response.pluginName Optional. Name of the plugin to be installed.
+ * @param {string} response.errorCode Error code for the error that occurred.
+ * @param {string} response.errorMessage The error that occurred.
*/
wp.updates.installImporterError = function( response ) {
var errorMessage = sprintf(
@@ -1321,11 +1321,11 @@
*
* @since 4.6.0
*
- * @param {Object} args Arguments.
- * @param {string} args.plugin Basename of the plugin to be deleted.
- * @param {string} args.slug Slug of the plugin to be deleted.
- * @param {deletePluginSuccess=} args.success Optional. Success callback. Default: wp.updates.deletePluginSuccess
- * @param {deletePluginError=} args.error Optional. Error callback. Default: wp.updates.deletePluginError
+ * @param {Object} args Arguments.
+ * @param {string} args.plugin Basename of the plugin to be deleted.
+ * @param {string} args.slug Slug of the plugin to be deleted.
+ * @param {deletePluginSuccess} args.success Optional. Success callback. Default: wp.updates.deletePluginSuccess
+ * @param {deletePluginError} args.error Optional. Error callback. Default: wp.updates.deletePluginError
* @return {$.promise} A jQuery promise that represents the request,
* decorated with an abort() method.
*/
@@ -1480,12 +1480,12 @@
*
* @since 4.6.0
*
- * @param {Object} response Response from the server.
- * @param {string} response.slug Slug of the plugin to be deleted.
- * @param {string} response.plugin Base name of the plugin to be deleted
- * @param {string=} response.pluginName Optional. Name of the plugin to be deleted.
- * @param {string} response.errorCode Error code for the error that occurred.
- * @param {string} response.errorMessage The error that occurred.
+ * @param {Object} response Response from the server.
+ * @param {string} response.slug Slug of the plugin to be deleted.
+ * @param {string} response.plugin Base name of the plugin to be deleted
+ * @param {string} response.pluginName Optional. Name of the plugin to be deleted.
+ * @param {string} response.errorCode Error code for the error that occurred.
+ * @param {string} response.errorMessage The error that occurred.
*/
wp.updates.deletePluginError = function( response ) {
var $plugin, $pluginUpdateRow,
@@ -1537,10 +1537,10 @@
*
* @since 4.6.0
*
- * @param {Object} args Arguments.
- * @param {string} args.slug Theme stylesheet.
- * @param {updateThemeSuccess=} args.success Optional. Success callback. Default: wp.updates.updateThemeSuccess
- * @param {updateThemeError=} args.error Optional. Error callback. Default: wp.updates.updateThemeError
+ * @param {Object} args Arguments.
+ * @param {string} args.slug Theme stylesheet.
+ * @param {updateThemeSuccess} args.success Optional. Success callback. Default: wp.updates.updateThemeSuccess
+ * @param {updateThemeError} args.error Optional. Error callback. Default: wp.updates.updateThemeError
* @return {$.promise} A jQuery promise that represents the request,
* decorated with an abort() method.
*/
@@ -1708,10 +1708,10 @@
*
* @since 4.6.0
*
- * @param {Object} args
- * @param {string} args.slug Theme stylesheet.
- * @param {installThemeSuccess=} args.success Optional. Success callback. Default: wp.updates.installThemeSuccess
- * @param {installThemeError=} args.error Optional. Error callback. Default: wp.updates.installThemeError
+ * @param {Object} args
+ * @param {string} args.slug Theme stylesheet.
+ * @param {installThemeSuccess} args.success Optional. Success callback. Default: wp.updates.installThemeSuccess
+ * @param {installThemeError} args.error Optional. Error callback. Default: wp.updates.installThemeError
* @return {$.promise} A jQuery promise that represents the request,
* decorated with an abort() method.
*/
@@ -1900,10 +1900,10 @@
*
* @since 4.6.0
*
- * @param {Object} args
- * @param {string} args.slug Theme stylesheet.
- * @param {deleteThemeSuccess=} args.success Optional. Success callback. Default: wp.updates.deleteThemeSuccess
- * @param {deleteThemeError=} args.error Optional. Error callback. Default: wp.updates.deleteThemeError
+ * @param {Object} args
+ * @param {string} args.slug Theme stylesheet.
+ * @param {deleteThemeSuccess} args.success Optional. Success callback. Default: wp.updates.deleteThemeSuccess
+ * @param {deleteThemeError} args.error Optional. Error callback. Default: wp.updates.deleteThemeError
* @return {$.promise} A jQuery promise that represents the request,
* decorated with an abort() method.
*/
@@ -2147,7 +2147,7 @@
*
* @since 4.2.0
*
- * @param {Event=} event Optional. Event interface.
+ * @param {Event} event Optional. Event interface.
*/
wp.updates.requestFilesystemCredentials = function( event ) {
if ( false === wp.updates.filesystemCredentials.available ) {
@@ -2169,7 +2169,7 @@
*
* @since 4.6.0
*
- * @param {Event=} event Optional. Event interface.
+ * @param {Event} event Optional. Event interface.
*/
wp.updates.maybeRequestFilesystemCredentials = function( event ) {
if ( wp.updates.shouldRequestFilesystemCredentials && ! wp.updates.ajaxLocked ) {
@@ -2325,12 +2325,13 @@
*
* If the response deems to be invalid, an admin notice is being displayed.
*
- * @param {(Object|string)} response Response from the server.
- * @param {function=} response.always Optional. Callback for when the Deferred is resolved or rejected.
- * @param {string=} response.statusText Optional. Status message corresponding to the status code.
- * @param {string=} response.responseText Optional. Request response as text.
- * @param {string} action Type of action the response is referring to. Can be 'delete',
- * 'update' or 'install'.
+ * @param {(Object|string)} response Response from the server.
+ * @param {Function} [response.always] Optional. Callback for when the Deferred is resolved or rejected.
+ * @param {string} [response.statusText] Optional. Status message corresponding to the status code.
+ * @param {string} [response.responseText] Optional. Request response as text.
+ * @param {string} action Type of action the response is referring to. Can be 'delete',
+ * 'update' or 'install'.
+ * @return {boolean} Whether the response is valid or not.
*/
wp.updates.isValidResponse = function( response, action ) {
var error = __( 'An error occurred during the update process. Please try again.' ),
@@ -2421,6 +2422,7 @@
* opens an "Are you sure?" alert.
*
* @since 4.2.0
+ * @return {string|void} Message to display in the "Are you sure?" alert, or nothing.
*/
wp.updates.beforeunload = function() {
if ( wp.updates.ajaxLocked ) {
diff --git a/src/js/_enqueues/wp/util.js b/src/js/_enqueues/wp/util.js
index f6425f2178bcb..e29fd3be462e8 100644
--- a/src/js/_enqueues/wp/util.js
+++ b/src/js/_enqueues/wp/util.js
@@ -18,7 +18,7 @@ window.wp = window.wp || {};
*
* @param {string} id A string that corresponds to a DOM element with an id prefixed with "tmpl-".
* For example, "attachment" maps to "tmpl-attachment".
- * @return {function} A function that lazily-compiles the template requested.
+ * @return {Function} A function that lazily-compiles the template requested.
*/
wp.template = _.memoize(function ( id ) {
var compiled,
@@ -60,9 +60,9 @@ window.wp = window.wp || {};
*
* Sends a POST request to WordPress.
*
- * @param {(string|Object)} action The slug of the action to fire in WordPress or options passed
- * to jQuery.ajax.
- * @param {Object=} data Optional. The data to populate $_POST with.
+ * @param {string|Object} action The slug of the action to fire in WordPress or options passed
+ * to jQuery.ajax.
+ * @param {Object} [data] Optional. The data to populate $_POST with.
* @return {$.promise} A jQuery promise that represents the request,
* decorated with an abort() method.
*/
@@ -77,9 +77,9 @@ window.wp = window.wp || {};
*
* Sends a POST request to WordPress.
*
- * @param {(string|Object)} action The slug of the action to fire in WordPress or options passed
- * to jQuery.ajax.
- * @param {Object=} options Optional. The options passed to jQuery.ajax.
+ * @param {(string|Object)} action The slug of the action to fire in WordPress or options passed
+ * to jQuery.ajax.
+ * @param {Object} [options] Optional. The options passed to jQuery.ajax.
* @return {$.promise} A jQuery promise that represents the request,
* decorated with an abort() method.
*/
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;
diff --git a/src/js/media/views/attachment-compat.js b/src/js/media/views/attachment-compat.js
index d24de569639bd..d9d8016d3bcfc 100644
--- a/src/js/media/views/attachment-compat.js
+++ b/src/js/media/views/attachment-compat.js
@@ -42,7 +42,7 @@ AttachmentCompat = View.extend(/** @lends wp.media.view.AttachmentCompat.prototy
return View.prototype.dispose.apply( this, arguments );
},
/**
- * @return {wp.media.view.AttachmentCompat} Returns itself to allow chaining.
+ * @return {void|wp.media.view.AttachmentCompat} Returns itself to allow chaining.
*/
render: function() {
var compat = this.model.get('compat');
diff --git a/src/js/media/views/attachment.js b/src/js/media/views/attachment.js
index 5761c959ea481..8a123d79de532 100644
--- a/src/js/media/views/attachment.js
+++ b/src/js/media/views/attachment.js
@@ -79,6 +79,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
this.listenTo( this.controller.states, 'attachment:compat:waiting attachment:compat:ready', this.updateSave );
},
/**
+ * Update the view after the model has been saved.
+ *
* @return {wp.media.view.Attachment} Returns itself to allow chaining.
*/
dispose: function() {
@@ -97,6 +99,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
return this;
},
/**
+ * Renders the attachment view.
+ *
* @return {wp.media.view.Attachment} Returns itself to allow chaining.
*/
render: function() {
@@ -167,6 +171,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
},
/**
+ * Toggles the selection state of the attachment.
+ *
* @param {Object} event
*/
toggleSelectionHandler: function( event ) {
@@ -221,6 +227,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
this.controller.trigger( 'selection:toggle' );
},
/**
+ * Toggles the selection state of the attachment.
+ *
* @param {Object} options
*/
toggleSelection: function( options ) {
@@ -301,7 +309,9 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
this[ this.selected() ? 'select' : 'deselect' ]();
},
/**
- * @return {unresolved|boolean}
+ * Checks if the model is selected in the selection.
+ *
+ * @return {void|boolean} True if the model is selected in the selection, false otherwise.
*/
selected: function() {
var selection = this.options.selection;
@@ -310,6 +320,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
}
},
/**
+ * Selects the model in the selection.
+ *
* @param {Backbone.Model} model
* @param {Backbone.Collection} collection
*/
@@ -339,6 +351,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
}
},
/**
+ * Deselects the model in the selection.
+ *
* @param {Backbone.Model} model
* @param {Backbone.Collection} collection
*/
@@ -357,6 +371,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
.find( '.check' ).attr( 'tabindex', '-1' );
},
/**
+ * Updates the view to reflect whether the model is the single model in the selection.
+ *
* @param {Backbone.Model} model
* @param {Backbone.Collection} collection
*/
@@ -372,8 +388,10 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
this.$el.toggleClass( 'details', details === this.model );
},
/**
+ * Gets the image size object for the specified size.
+ *
* @param {string} size
- * @return {Object}
+ * @return {Object} Returns an object containing the image size information.
*/
imageSize: function( size ) {
var sizes = this.model.get('sizes'), matched = false;
@@ -405,6 +423,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
};
},
/**
+ * Update the model's setting with the value from the input.
+ *
* @param {Object} event
*/
updateSetting: function( event ) {
@@ -456,6 +476,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
});
},
/**
+ * Updates the view's save status.
+ *
* @param {string} status
* @return {wp.media.view.Attachment} Returns itself to allow chaining.
*/
@@ -498,6 +520,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
}
},
/**
+ * Removes the model from the collection.
+ *
* @param {Object} event
*/
removeFromLibrary: function( event ) {
@@ -513,11 +537,11 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
},
/**
- * Add the model if it isn't in the selection, if it is in the selection,
- * remove it.
+ * Adds the model if it isn't in the selection, if it is in the selection,
+ * removes it.
*
- * @param {[type]} event [description]
- * @return {[type]} [description]
+ * @param {Object} event
+ * @return {void}
*/
checkClickHandler: function ( event ) {
var selection = this.options.selection;
diff --git a/src/js/media/views/attachment/details.js b/src/js/media/views/attachment/details.js
index 8f450be793cfb..a4ed635b62442 100644
--- a/src/js/media/views/attachment/details.js
+++ b/src/js/media/views/attachment/details.js
@@ -33,8 +33,6 @@ Details = Attachment.extend(/** @lends wp.media.view.Attachment.Details.prototyp
*
* @since 5.5.0
*
- * @param {MouseEvent} event A click event.
- *
* @return {void}
*/
copyAttachmentDetailsURLClipboard: function() {
diff --git a/src/js/media/views/attachments/browser.js b/src/js/media/views/attachments/browser.js
index 82b7359eb832a..889978eaf78ec 100644
--- a/src/js/media/views/attachments/browser.js
+++ b/src/js/media/views/attachments/browser.js
@@ -17,7 +17,7 @@ var View = wp.media.View,
* @augments wp.Backbone.View
* @augments Backbone.View
*
- * @param {object} [options] The options hash passed to the view.
+ * @param {Object} [options] The options hash passed to the view.
* @param {boolean|string} [options.filters=false] Which filters to show in the browser's toolbar.
* Accepts 'uploaded' and 'all'.
* @param {boolean} [options.search=true] Whether to show the search interface in the
diff --git a/src/js/media/views/button-group.js b/src/js/media/views/button-group.js
index bf5fe968bc187..e0fd09b0d957d 100644
--- a/src/js/media/views/button-group.js
+++ b/src/js/media/views/button-group.js
@@ -35,7 +35,9 @@ ButtonGroup = wp.media.View.extend(/** @lends wp.media.view.ButtonGroup.prototyp
},
/**
- * @return {wp.media.view.ButtonGroup}
+ * Renders the button group.
+ *
+ * @return {wp.media.view.ButtonGroup} The button group.
*/
render: function() {
this.$el.html( $( _.pluck( this.buttons, 'el' ) ).detach() );
diff --git a/src/js/media/views/embed/url.js b/src/js/media/views/embed/url.js
index 701b2859518e1..42c620dda4530 100644
--- a/src/js/media/views/embed/url.js
+++ b/src/js/media/views/embed/url.js
@@ -39,7 +39,9 @@ EmbedUrl = View.extend(/** @lends wp.media.view.EmbedUrl.prototype */{
}
},
/**
- * @return {wp.media.view.EmbedUrl} Returns itself to allow chaining.
+ * Renders the view.
+ *
+ * @return {void|wp.media.view.EmbedUrl} Returns itself to allow chaining.
*/
render: function() {
var $input = this.$input;
diff --git a/src/js/media/views/focus-manager.js b/src/js/media/views/focus-manager.js
index d79961b05b89c..36ef6a851b0da 100644
--- a/src/js/media/views/focus-manager.js
+++ b/src/js/media/views/focus-manager.js
@@ -218,8 +218,6 @@ var FocusManager = wp.media.View.extend(/** @lends wp.media.view.FocusManager.pr
*
* @since 5.3.0
*
- * @param {Object} event jQuery event object.
- *
* @return {void}
*/
setupAriaTabs: function() {
diff --git a/src/js/media/views/frame.js b/src/js/media/views/frame.js
index 8805bc7de45e2..851557d9f3ccb 100644
--- a/src/js/media/views/frame.js
+++ b/src/js/media/views/frame.js
@@ -88,6 +88,10 @@ var Frame = wp.media.View.extend(/** @lends wp.media.view.Frame.prototype */{
},
/**
* Map activeMode collection events to the frame.
+ *
+ * @param {Backbone.Model} model
+ * @param {Backbone.Collection} collection
+ * @param {Object} options
*/
triggerModeEvents: function( model, collection, options ) {
var collectionEvent,
@@ -113,8 +117,8 @@ var Frame = wp.media.View.extend(/** @lends wp.media.view.Frame.prototype */{
/**
* Activate a mode on the frame.
*
- * @param string mode Mode ID.
- * @return {this} Returns itself to allow chaining.
+ * @param {string} mode Mode ID.
+ * @return {void|this} Returns itself to allow chaining.
*/
activateMode: function( mode ) {
// Bail if the mode is already active.
@@ -130,7 +134,7 @@ var Frame = wp.media.View.extend(/** @lends wp.media.view.Frame.prototype */{
/**
* Deactivate a mode on the frame.
*
- * @param string mode Mode ID.
+ * @param {string} mode Mode ID.
* @return {this} Returns itself to allow chaining.
*/
deactivateMode: function( mode ) {
@@ -152,8 +156,8 @@ var Frame = wp.media.View.extend(/** @lends wp.media.view.Frame.prototype */{
/**
* Check if a mode is enabled on the frame.
*
- * @param string mode Mode ID.
- * @return bool
+ * @param {string} mode Mode ID.
+ * @return {boolean} True if the mode is active, false otherwise.
*/
isModeActive: function( mode ) {
return Boolean( this.activeModes.where( { id: mode } ).length );
diff --git a/src/js/media/views/frame/edit-attachments.js b/src/js/media/views/frame/edit-attachments.js
index f6bb4b8afa2cc..e3bc0d09e643b 100644
--- a/src/js/media/views/frame/edit-attachments.js
+++ b/src/js/media/views/frame/edit-attachments.js
@@ -207,6 +207,7 @@ EditAttachments = MediaFrame.extend(/** @lends wp.media.view.MediaFrame.EditAtta
/**
* Rerender the view.
+ * @param {wp.media.model.Attachment} model The attachment model to render.
*/
rerender: function( model ) {
this.stopListening( this.model );
@@ -285,6 +286,8 @@ EditAttachments = MediaFrame.extend(/** @lends wp.media.view.MediaFrame.EditAtta
* Respond to the keyboard events: Alt + right arrow, Alt + left arrow,
* except when focus is in a form field. Requires the Alt modifier key to
* avoid interfering with screen reader navigation.
+ *
+ * @param {Event} event The keyboard event.
*/
keyEvent: function( event ) {
if ( ( 'INPUT' === event.target.nodeName || 'TEXTAREA' === event.target.nodeName || 'SELECT' === event.target.nodeName ) && ! event.target.disabled ) {
diff --git a/src/js/media/views/frame/manage.js b/src/js/media/views/frame/manage.js
index ea16637fdf7a5..2fb32e09eac74 100644
--- a/src/js/media/views/frame/manage.js
+++ b/src/js/media/views/frame/manage.js
@@ -196,6 +196,8 @@ Manage = MediaFrame.extend(/** @lends wp.media.view.MediaFrame.Manage.prototype
/**
* Click handler for the `Add New` button.
+ *
+ * @param {Event} event The click event.
*/
addNewClickHandler: function( event ) {
event.preventDefault();
@@ -208,6 +210,8 @@ Manage = MediaFrame.extend(/** @lends wp.media.view.MediaFrame.Manage.prototype
/**
* Open the Edit Attachment modal.
+ *
+ * @param {wp.media.model.Attachment} model The attachment model to edit.
*/
openEditAttachmentModal: function( model ) {
// Create a new EditAttachment frame, passing along the library and the attachment model.
diff --git a/src/js/media/views/media-details.js b/src/js/media/views/media-details.js
index 19b1fb0d9c253..eab736e5c8303 100644
--- a/src/js/media/views/media-details.js
+++ b/src/js/media/views/media-details.js
@@ -148,7 +148,7 @@ MediaDetails = AttachmentDisplay.extend(/** @lends wp.media.view.MediaDetails.pr
* When multiple players in the DOM contain the same src, things get weird.
*
* @param {HTMLElement} elem
- * @return {HTMLElement}
+ * @return {HTMLElement} The prepared element.
*/
prepareSrc : function( elem ) {
var i = MediaDetails.instances++;
diff --git a/src/js/media/views/menu.js b/src/js/media/views/menu.js
index cf967c83bb4f6..97f4f0f436ab8 100644
--- a/src/js/media/views/menu.js
+++ b/src/js/media/views/menu.js
@@ -48,7 +48,7 @@ Menu = PriorityList.extend(/** @lends wp.media.view.Menu.prototype */{
/**
* @param {Object} options
* @param {string} id
- * @return {wp.media.View}
+ * @return {wp.media.View} The view instance.
*/
toView: function( options, id ) {
options = options || {};
diff --git a/src/js/media/views/modal.js b/src/js/media/views/modal.js
index cfc396bf8039b..29150515a45cd 100644
--- a/src/js/media/views/modal.js
+++ b/src/js/media/views/modal.js
@@ -37,7 +37,9 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{
});
},
/**
- * @return {Object}
+ * Prepares the data for the modal template.
+ *
+ * @return {Object} The prepared data.
*/
prepare: function() {
return {
@@ -47,6 +49,8 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{
},
/**
+ * Attaches the modal to the DOM and triggers the ready event.
+ *
* @return {wp.media.view.Modal} Returns itself to allow chaining.
*/
attach: function() {
@@ -68,6 +72,8 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{
},
/**
+ * Detaches the modal from the DOM and triggers the detach event.
+ *
* @return {wp.media.view.Modal} Returns itself to allow chaining.
*/
detach: function() {
@@ -81,6 +87,8 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{
},
/**
+ * Opens the modal and triggers the open event.
+ *
* @return {wp.media.view.Modal} Returns itself to allow chaining.
*/
open: function() {
@@ -124,6 +132,8 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{
},
/**
+ * Closes the modal and triggers the close event.
+ *
* @param {Object} options
* @return {wp.media.view.Modal} Returns itself to allow chaining.
*/
@@ -167,12 +177,16 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{
return this;
},
/**
+ * Closes the modal and triggers the escape event.
+ *
* @return {wp.media.view.Modal} Returns itself to allow chaining.
*/
escape: function() {
return this.close({ escape: true });
},
/**
+ * Handles the escape key press event to close the modal.
+ *
* @param {Object} event
*/
escapeHandler: function( event ) {
@@ -204,6 +218,8 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{
},
/**
+ * Sets the content of the modal by registering views to the '.media-modal-content' selector.
+ *
* @param {Array|Object} content Views to register to '.media-modal-content'
* @return {wp.media.view.Modal} Returns itself to allow chaining.
*/
@@ -229,6 +245,8 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{
return this;
},
/**
+ * Handles keydown events within the modal.
+ *
* @param {Object} event
*/
keydown: function( event ) {
diff --git a/src/js/media/views/priority-list.js b/src/js/media/views/priority-list.js
index 65e7cde20ddd2..28a83f753d78b 100644
--- a/src/js/media/views/priority-list.js
+++ b/src/js/media/views/priority-list.js
@@ -22,6 +22,8 @@ var PriorityList = wp.media.View.extend(/** @lends wp.media.view.PriorityList.pr
}
},
/**
+ * Adds a view to the list, sorted by its priority.
+ *
* @param {string} id
* @param {wp.media.View|Object} view
* @param {Object} options
@@ -65,15 +67,19 @@ var PriorityList = wp.media.View.extend(/** @lends wp.media.view.PriorityList.pr
return this;
},
/**
+ * Retrieves a view by its ID.
+ *
* @param {string} id
- * @return {wp.media.View}
+ * @return {wp.media.View} Returns the view if found, otherwise undefined.
*/
get: function( id ) {
return this._views[ id ];
},
/**
+ * Removes a view by its ID.
+ *
* @param {string} id
- * @return {wp.media.view.PriorityList}
+ * @return {wp.media.view.PriorityList} Returns itself to allow chaining.
*/
unset: function( id ) {
var view = this.get( id );
@@ -86,8 +92,10 @@ var PriorityList = wp.media.View.extend(/** @lends wp.media.view.PriorityList.pr
return this;
},
/**
+ * Creates a view from an object of options.
+ *
* @param {Object} options
- * @return {wp.media.View}
+ * @return {wp.media.View} Returns the created view.
*/
toView: function( options ) {
return new wp.media.View( options );
diff --git a/src/js/media/views/toolbar.js b/src/js/media/views/toolbar.js
index ff98d13b0a316..c22dfc53dbfcd 100644
--- a/src/js/media/views/toolbar.js
+++ b/src/js/media/views/toolbar.js
@@ -109,8 +109,10 @@ Toolbar = View.extend(/** @lends wp.media.view.Toolbar.prototype */{
return this;
},
/**
+ * Retrieves a view by its ID.
+ *
* @param {string} id
- * @return {wp.media.view.Button}
+ * @return {wp.media.view.Button} The view associated with the given ID, or undefined if no view is found.
*/
get: function( id ) {
return this._views[ id ];
diff --git a/src/js/media/views/uploader/editor.js b/src/js/media/views/uploader/editor.js
index 824d7253f80d8..4ea1c310b73c9 100644
--- a/src/js/media/views/uploader/editor.js
+++ b/src/js/media/views/uploader/editor.js
@@ -28,6 +28,8 @@ EditorUploader = View.extend(/** @lends wp.media.view.EditorUploader.prototype *
/**
* Bind drag'n'drop events to callbacks.
+ *
+ * @return {wp.media.view.EditorUploader} Chainable.
*/
initialize: function() {
this.initialized = false;
@@ -64,7 +66,7 @@ EditorUploader = View.extend(/** @lends wp.media.view.EditorUploader.prototype *
/**
* Check browser support for drag'n'drop.
*
- * @return {boolean}
+ * @return {boolean} True if the browser supports drag'n'drop, false otherwise.
*/
browserSupport: function() {
var supports = false, div = document.createElement('div');
@@ -130,6 +132,7 @@ EditorUploader = View.extend(/** @lends wp.media.view.EditorUploader.prototype *
* and upload the file immediately.
*
* @param {jQuery.Event} event The 'drop' event.
+ * @return {void|boolean} False to prevent default behavior.
*/
drop: function( event ) {
var $wrap, uploadView;
@@ -174,6 +177,8 @@ EditorUploader = View.extend(/** @lends wp.media.view.EditorUploader.prototype *
/**
* Add the files to the uploader.
+ *
+ * @return {wp.media.view.EditorUploader} Chainable.
*/
addFiles: function() {
if ( this.files.length ) {
diff --git a/src/js/media/views/uploader/inline.js b/src/js/media/views/uploader/inline.js
index 992d2eed02542..eedca1aa24d03 100644
--- a/src/js/media/views/uploader/inline.js
+++ b/src/js/media/views/uploader/inline.js
@@ -60,11 +60,13 @@ UploaderInline = View.extend(/** @lends wp.media.view.UploaderInline.prototype *
return data;
},
/**
+ * Disposes of the inline uploader and its associated views.
+ *
* @return {wp.media.view.UploaderInline} Returns itself to allow chaining.
*/
dispose: function() {
if ( this.disposing ) {
- /**
+ /*
* call 'dispose' directly on the parent class
*/
return View.prototype.dispose.apply( this, arguments );
@@ -79,10 +81,12 @@ UploaderInline = View.extend(/** @lends wp.media.view.UploaderInline.prototype *
return this.remove();
},
/**
+ * Disposes of the inline uploader and its associated views.
+ *
* @return {wp.media.view.UploaderInline} Returns itself to allow chaining.
*/
remove: function() {
- /**
+ /*
* call 'remove' directly on the parent class
*/
var result = View.prototype.remove.apply( this, arguments );
@@ -99,7 +103,9 @@ UploaderInline = View.extend(/** @lends wp.media.view.UploaderInline.prototype *
}
},
/**
- * @return {wp.media.view.UploaderInline}
+ * Replaces the placeholder with the uploader browser and refreshes the uploader.
+ *
+ * @return {void|wp.media.view.UploaderInline} Returns itself to allow chaining.
*/
ready: function() {
var $browser = this.options.$browser,
diff --git a/src/js/media/views/uploader/status.js b/src/js/media/views/uploader/status.js
index f629e0a34365f..370f4df223ece 100644
--- a/src/js/media/views/uploader/status.js
+++ b/src/js/media/views/uploader/status.js
@@ -33,11 +33,13 @@ UploaderStatus = View.extend(/** @lends wp.media.view.UploaderStatus.prototype *
this.errors.on( 'add', this.error, this );
},
/**
- * @return {wp.media.view.UploaderStatus}
+ * Disposes of the uploader status and its associated views.
+ *
+ * @return {wp.media.view.UploaderStatus} Returns the instance of the UploaderStatus view.
*/
dispose: function() {
wp.Uploader.queue.off( null, null, this );
- /**
+ /*
* call 'dispose' directly on the parent class
*/
View.prototype.dispose.apply( this, arguments );
@@ -103,14 +105,19 @@ UploaderStatus = View.extend(/** @lends wp.media.view.UploaderStatus.prototype *
}
},
/**
+ * Escapes the filename to prevent XSS attacks.
+ *
* @param {string} filename
- * @return {string}
+ * @return {string} Escaped filename.
*/
filename: function( filename ) {
return _.escape( filename );
},
/**
+ * Handles an error event from the uploader queue.
+ *
* @param {Backbone.Model} error
+ * @return {void}
*/
error: function( error ) {
var statusError = new wp.media.view.UploaderStatusError( {
@@ -131,6 +138,9 @@ UploaderStatus = View.extend(/** @lends wp.media.view.UploaderStatus.prototype *
}, 1500 );
},
+ /**
+ * Dismisses the error messages and resets the uploader errors.
+ */
dismiss: function() {
var errors = this.views.get('.upload-errors');
diff --git a/src/js/media/views/uploader/window.js b/src/js/media/views/uploader/window.js
index 84b158f7cce61..0cd97f7c9dd76 100644
--- a/src/js/media/views/uploader/window.js
+++ b/src/js/media/views/uploader/window.js
@@ -13,11 +13,11 @@ var $ = jQuery,
* @augments wp.Backbone.View
* @augments Backbone.View
*
- * @param {object} [options] Options hash passed to the view.
- * @param {object} [options.uploader] Uploader properties.
+ * @param {Object} [options] Options hash passed to the view.
+ * @param {Object} [options.uploader] Uploader properties.
* @param {jQuery} [options.uploader.browser]
* @param {jQuery} [options.uploader.dropzone] jQuery collection of the dropzone.
- * @param {object} [options.uploader.params]
+ * @param {Object} [options.uploader.params]
*/
UploaderWindow = wp.media.View.extend(/** @lends wp.media.view.UploaderWindow.prototype */{
tagName: 'div',