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/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/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. */