diff --git a/.eslintrc-jsdoc.js b/.eslintrc-jsdoc.js index dc6559c520cbe..93c13a857b7b3 100644 --- a/.eslintrc-jsdoc.js +++ b/.eslintrc-jsdoc.js @@ -36,6 +36,21 @@ module.exports = [ }, }, rules: { + 'jsdoc/check-alignment': 'error', + 'jsdoc/check-indentation': [ 'error', { + excludeTags: [ + 'deprecated', + 'example', + 'param', + 'property', + 'return', + 'since', + 'todo', + ], + } ], + 'jsdoc/check-line-alignment': [ 'error', 'always', { + tags: [ 'param', 'property' ], + } ], 'jsdoc/check-param-names': 'error', 'jsdoc/check-syntax': 'error', 'jsdoc/check-tag-names': [ 'error', { @@ -48,6 +63,7 @@ module.exports = [ } ], 'jsdoc/check-types': 'error', 'jsdoc/require-description': 'error', + 'jsdoc/require-hyphen-before-param-description': [ 'error', 'never' ], 'jsdoc/require-jsdoc': 'error', 'jsdoc/require-param': [ 'error', { enableFixer: false, diff --git a/src/js/_enqueues/admin/application-passwords.js b/src/js/_enqueues/admin/application-passwords.js index ab3d2fc4de35a..21fbeb65820af 100644 --- a/src/js/_enqueues/admin/application-passwords.js +++ b/src/js/_enqueues/admin/application-passwords.js @@ -172,8 +172,8 @@ * * @since 5.6.0 * - * @param {jqXHR} xhr The XHR object from the ajax call. - * @param {string} textStatus The string categorizing the ajax request's status. + * @param {jqXHR} xhr The XHR object from the ajax call. + * @param {string} textStatus The string categorizing the ajax request's status. * @param {string} errorThrown The HTTP status error text. */ function handleErrorResponse( xhr, textStatus, errorThrown ) { diff --git a/src/js/_enqueues/admin/common.js b/src/js/_enqueues/admin/common.js index 735a9aeeaabef..fe83cc7e9f2ae 100644 --- a/src/js/_enqueues/admin/common.js +++ b/src/js/_enqueues/admin/common.js @@ -2,15 +2,14 @@ * @output wp-admin/js/common.js */ -/* global setUserSetting, ajaxurl, alert, confirm, pagenow */ -/* global columns, screenMeta */ +/* global setUserSetting, ajaxurl, alert, confirm, pagenow, columns, screenMeta */ /** - * Adds common WordPress functionality to the window. + * Adds common WordPress functionality to the window. * - * @param {JQueryStatic} $ The jQuery object. - * @param {Object} window The window object. - * @param {*} undefined Unused. + * @param {JQueryStatic} $ The jQuery object. + * @param {Object} window The window object. + * @param {*} undefined Unused. */ ( function( $, window, undefined ) { var $document = $( document ), @@ -568,8 +567,8 @@ window.showNotice = { * @since 3.2.0 * * @type {{element: null, toggles: null, page: null, init: screenMeta.init, - * toggleEvent: screenMeta.toggleEvent, open: screenMeta.open, - * close: screenMeta.close}} + * toggleEvent: screenMeta.toggleEvent, open: screenMeta.open, + * close: screenMeta.close}} * * @return {void} */ @@ -980,8 +979,8 @@ $( function() { /* * Show the sub instead of following the link if: - * - the submenu is not open. - * - the submenu is not shown inline or the menu is not folded. + * - the submenu is not open. + * - the submenu is not shown inline or the menu is not folded. */ if ( ! $menuItem.hasClass( 'opensub' ) && ( ! $menuItem.hasClass( 'wp-menu-open' ) || $menuItem.width() < 40 ) ) { event.preventDefault(); @@ -1485,7 +1484,7 @@ $( function() { * @param {Event} e The event object. * * @return {void} - */ + */ $('#contextual-help-link, #show-settings-link').on( 'focus.scroll-into-view', function(e){ if ( e.target.scrollIntoViewIfNeeded ) e.target.scrollIntoViewIfNeeded(false); diff --git a/src/js/_enqueues/admin/custom-background.js b/src/js/_enqueues/admin/custom-background.js index d8ef84e618bc1..b10a72296d2c6 100644 --- a/src/js/_enqueues/admin/custom-background.js +++ b/src/js/_enqueues/admin/custom-background.js @@ -124,7 +124,7 @@ * @since 3.5.0 * * @return {void} - */ + */ frame.on( 'select', function() { // Grab the selected attachment. var attachment = frame.state().get('selection').first(); diff --git a/src/js/_enqueues/admin/edit-comments.js b/src/js/_enqueues/admin/edit-comments.js index b6763c386149e..7e89f1c0dd7cb 100644 --- a/src/js/_enqueues/admin/edit-comments.js +++ b/src/js/_enqueues/admin/edit-comments.js @@ -42,7 +42,7 @@ var getCount, updateCount, updateCountText, updatePending, updateApproved, * @access private * * @param {jQuery} el The jQuery element to update. - * @param {number} n Number to be put in the element. + * @param {number} n Number to be put in the element. * * @return {void} */ @@ -68,7 +68,7 @@ var getCount, updateCount, updateCountText, updatePending, updateApproved, * @since 4.4.0 * @access private * - * @param {number} diff The amount to lower or raise the approved count with. + * @param {number} diff The amount to lower or raise the approved count with. * @param {number} commentPostId The ID of the post to be updated. * * @return {void} @@ -122,7 +122,7 @@ var getCount, updateCount, updateCountText, updatePending, updateApproved, * * @param {string} selector The jQuery selector for elements to update a count * for. - * @param {number} diff The amount to lower or raise the count with. + * @param {number} diff The amount to lower or raise the count with. * * @return {void} */ @@ -231,7 +231,7 @@ var getCount, updateCount, updateCountText, updatePending, updateApproved, * @since 3.2.0 * @access private * - * @param {number} diff The amount to lower or raise the pending count with. + * @param {number} diff The amount to lower or raise the pending count with. * @param {number} commentPostId The ID of the post to be updated. * * @return {void} @@ -322,9 +322,9 @@ window.setCommentsList = function() { * @since 2.8.0 * @access private * - * @param {number} total Total number of comments. - * @param {number} time Unix timestamp of response. - * @param {boolean} setConfidentTime Whether to update the last confident time + * @param {number} total Total number of comments. + * @param {number} time Unix timestamp of response. + * @param {boolean} setConfidentTime Whether to update the last confident time * with the given time. * * @return {void} @@ -345,7 +345,7 @@ window.setCommentsList = function() { * @since 2.5.0 * @access private * - * @param {Object} r Ajax response object. + * @param {Object} r Ajax response object. * @param {Object} settings Settings for the wpList object. * * @return {void} @@ -398,8 +398,8 @@ window.setCommentsList = function() { * @since 2.8.0 * @access private * - * @param {Object} settings Settings for the wpList object. - * @param {HTMLElement} list Comments table element. + * @param {Object} settings Settings for the wpList object. + * @param {HTMLElement} list Comments table element. * * @return {Object} The settings object. */ @@ -471,7 +471,7 @@ window.setCommentsList = function() { * @since 2.5.0 * @access private * - * @param {Object} r Ajax response object. + * @param {Object} r Ajax response object. * @param {Object} settings Settings for the wpList object. * * @return {void} @@ -945,8 +945,8 @@ window.commentReply = { * @memberof commentReply * * @param {number} comment_id The comment ID to open an editor for. - * @param {number} post_id The post ID to open an editor for. - * @param {string} action The action to perform. Either 'edit' or 'replyto'. + * @param {number} post_id The post ID to open an editor for. + * @param {string} action The action to perform. Either 'edit' or 'replyto'. * * @return {boolean} Always false. */ diff --git a/src/js/_enqueues/admin/inline-edit-post.js b/src/js/_enqueues/admin/inline-edit-post.js index 7f469137fc1bd..aaf4bcc5bc3ec 100644 --- a/src/js/_enqueues/admin/inline-edit-post.js +++ b/src/js/_enqueues/admin/inline-edit-post.js @@ -18,11 +18,11 @@ window.wp = window.wp || {}; * * @type {Object} * - * @property {string} type The type of inline editor. - * @property {string} what The prefix before the post ID. + * @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. + * @param {JQueryStatic} $ The jQuery object. + * @param {wp} wp The WordPress global object. * */ ( function( $, wp ) { diff --git a/src/js/_enqueues/admin/inline-edit-tax.js b/src/js/_enqueues/admin/inline-edit-tax.js index 620533455f6be..cedbefa256d93 100644 --- a/src/js/_enqueues/admin/inline-edit-tax.js +++ b/src/js/_enqueues/admin/inline-edit-tax.js @@ -13,12 +13,11 @@ window.wp = window.wp || {}; * * @namespace inlineEditTax * - * @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. + * @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. + * @param {JQueryStatic} $ The jQuery object. + * @param {Object} wp The WordPress object. */ ( function( $, wp ) { @@ -117,7 +116,7 @@ window.inlineEditTax = { * * @param {string|HTMLElement} id The ID of the term we want to quick edit or an * element within the table row or the - * table row itself. + * table row itself. * @return {boolean} Always returns false. */ edit : function(id) { @@ -164,7 +163,7 @@ window.inlineEditTax = { * * @param {string|HTMLElement} id The ID of the term we want to quick edit or an * element within the table row or the - * table row itself. + * table row itself. * @return {boolean} Always returns false. */ save : function(id) { diff --git a/src/js/_enqueues/admin/media.js b/src/js/_enqueues/admin/media.js index db61220b50e5f..f464fe960b03f 100644 --- a/src/js/_enqueues/admin/media.js +++ b/src/js/_enqueues/admin/media.js @@ -24,7 +24,7 @@ * @memberOf findPosts * * @param {string} af_name The name of the affected element. - * @param {string} af_val The value of the affected post element. + * @param {string} af_val The value of the affected post element. * * @return {boolean} Always returns false. */ diff --git a/src/js/_enqueues/admin/postbox.js b/src/js/_enqueues/admin/postbox.js index 1f101d3fd1c41..fd227b798eafb 100644 --- a/src/js/_enqueues/admin/postbox.js +++ b/src/js/_enqueues/admin/postbox.js @@ -353,8 +353,8 @@ * * @memberof postboxes * - * @param {string} page The page we are currently on. - * @param {Object} [args={}] The arguments for the postbox initializer. + * @param {string} page The page we are currently on. + * @param {Object} [args={}] The arguments for the postbox initializer. * @param {Function} args.pbshow A callback that is called when a postbox opens. * @param {Function} args.pbhide A callback that is called when a postbox * closes. diff --git a/src/js/_enqueues/admin/tags-box.js b/src/js/_enqueues/admin/tags-box.js index 99d664691c9c8..a3e1e901be22c 100644 --- a/src/js/_enqueues/admin/tags-box.js +++ b/src/js/_enqueues/admin/tags-box.js @@ -219,11 +219,11 @@ * * @memberOf tagBox * - * @param {Object} el The container HTML element. - * @param {Object|boolean} a When this is an HTML element the text of that - * element will be used for the new tag. - * @param {number|boolean} f If this value is not passed then the tag input - * field is focused. + * @param {Object} el The container HTML element. + * @param {Object|boolean} a When this is an HTML element the text of that + * element will be used for the new tag. + * @param {number|boolean} f If this value is not passed then the tag input + * field is focused. * * @return {boolean} Always returns false. */ @@ -287,8 +287,8 @@ * * @since 2.9.0 * - * @param {number|string} r The response message from the Ajax call. - * @param {string} stat The status of the Ajax request. + * @param {number|string} r The response message from the Ajax call. + * @param {string} stat The status of the Ajax request. * * @return {void} */ diff --git a/src/js/_enqueues/admin/widgets.js b/src/js/_enqueues/admin/widgets.js index cbd8f8dd4a222..f63f0182853ef 100644 --- a/src/js/_enqueues/admin/widgets.js +++ b/src/js/_enqueues/admin/widgets.js @@ -752,7 +752,7 @@ $( function(){ wpWidgets.init(); } ); * @deprecated 5.5.0 * * @type {Object} -*/ + */ wpWidgets.l10n = wpWidgets.l10n || { save: '', saved: '', diff --git a/src/js/_enqueues/lib/accordion.js b/src/js/_enqueues/lib/accordion.js index 867b6d7ac0a04..1310033f4c1ff 100644 --- a/src/js/_enqueues/lib/accordion.js +++ b/src/js/_enqueues/lib/accordion.js @@ -5,6 +5,8 @@ * with one section opening at a time when its title is clicked. * Use the following markup structure for accordion behavior: * + * @example + * ```html *
*
*

@@ -22,6 +24,7 @@ *
*
* + * ``` * * Note that any appropriate tags may be used, as long as the above classes are present. * diff --git a/src/js/_enqueues/lib/admin-bar.js b/src/js/_enqueues/lib/admin-bar.js index 3d6f4e3c8b94d..4430ccc7ecb77 100644 --- a/src/js/_enqueues/lib/admin-bar.js +++ b/src/js/_enqueues/lib/admin-bar.js @@ -174,7 +174,7 @@ * @since 5.3.1 * * @param {NodeList} topMenuItems All menu items. - * @param {Event} event The click event. + * @param {Event} event The click event. */ function mobileHover( topMenuItems, event ) { var wrapper; @@ -260,7 +260,7 @@ * * @since 5.3.1 * - * @param {HTMLElement} element The HTML element. + * @param {HTMLElement} element The HTML element. * @param {string} className The class name. * @return {boolean} Whether the element has the className. */ @@ -286,7 +286,7 @@ * * @since 5.3.1 * - * @param {HTMLElement} element The HTML element. + * @param {HTMLElement} element The HTML element. * @param {string} className The class name. */ function addClass( element, className ) { @@ -315,7 +315,7 @@ * * @since 5.3.1 * - * @param {HTMLElement} element The HTML element. + * @param {HTMLElement} element The HTML element. * @param {string} className The class name. */ function removeClass( element, className ) { @@ -395,8 +395,8 @@ * * @since 5.3.1 * - * @param {HTMLElement} el Element to get parent. - * @param {string} selector CSS selector to match. + * @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. */ diff --git a/src/js/_enqueues/lib/auth-check.js b/src/js/_enqueues/lib/auth-check.js index 1617da0cb25bd..f05d6643bf776 100644 --- a/src/js/_enqueues/lib/auth-check.js +++ b/src/js/_enqueues/lib/auth-check.js @@ -137,14 +137,13 @@ * Binds to the Heartbeat Tick event. * * - Shows the authentication form popup if user is not logged in. - * - Hides the authentication form popup if it is already visible and user is - * logged in. + * - Hides the authentication form popup if it is already visible and user is logged in. * * @ignore * * @since 3.6.0 * - * @param {Object} e The heartbeat-tick event that has been triggered. + * @param {Object} e The heartbeat-tick event that has been triggered. * @param {Object} data Response data. */ $( function() { diff --git a/src/js/_enqueues/lib/codemirror/htmlhint-kses.js b/src/js/_enqueues/lib/codemirror/htmlhint-kses.js index e08c4c0f5b756..e40a8ca8f3631 100644 --- a/src/js/_enqueues/lib/codemirror/htmlhint-kses.js +++ b/src/js/_enqueues/lib/codemirror/htmlhint-kses.js @@ -8,9 +8,9 @@ HTMLHint.addRule( { * Initialize. * * @this {import('htmlhint/types').Rule} - * @param {import('htmlhint').HTMLParser} parser - Parser. - * @param {import('htmlhint').Reporter} reporter - Reporter. - * @param {Record>} options - KSES options. + * @param {import('htmlhint').HTMLParser} parser Parser. + * @param {import('htmlhint').Reporter} reporter Reporter. + * @param {Record>} options KSES options. * @return {void} */ init: function ( parser, reporter, options ) { diff --git a/src/js/_enqueues/lib/codemirror/javascript-lint.js b/src/js/_enqueues/lib/codemirror/javascript-lint.js index 74c4cbacc0c5f..15fefe832805c 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,7 +38,7 @@ import CodeMirror from 'codemirror'; * * @since 7.0.0 * - * @param {string} text Source. + * @param {string} text Source. * @param {SupportedJSHintOptions} options Linting options. * @return {Promise} Linting errors. */ diff --git a/src/js/_enqueues/lib/color-picker.js b/src/js/_enqueues/lib/color-picker.js index bcf3d0eb842a4..d8258c53de22c 100644 --- a/src/js/_enqueues/lib/color-picker.js +++ b/src/js/_enqueues/lib/color-picker.js @@ -69,8 +69,8 @@ * * @ignore * - * @param {Event} event The event that's being called. - * @param {HTMLElement} ui The HTMLElement containing the color picker. + * @param {Event} event The event that's being called. + * @param {HTMLElement} ui The HTMLElement containing the color picker. * * @return {void} */ @@ -189,8 +189,8 @@ * * @ignore * - * @param {Event} event The event that's being called. - * @param {HTMLElement} ui The HTMLElement containing the color picker. + * @param {Event} event The event that's being called. + * @param {HTMLElement} ui The HTMLElement containing the color picker. * * @return {void} */ diff --git a/src/js/_enqueues/lib/cookies.js b/src/js/_enqueues/lib/cookies.js index 30a29d496a02e..bb398fe8ce487 100644 --- a/src/js/_enqueues/lib/cookies.js +++ b/src/js/_enqueues/lib/cookies.js @@ -63,12 +63,12 @@ window.wpCookies = { * * '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. + * @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 = ''; diff --git a/src/js/_enqueues/lib/emoji-loader.js b/src/js/_enqueues/lib/emoji-loader.js index 86963a2a3af24..5bce5aa43a44e 100644 --- a/src/js/_enqueues/lib/emoji-loader.js +++ b/src/js/_enqueues/lib/emoji-loader.js @@ -57,7 +57,7 @@ function supportsWorkerOffloading() { /** * @typedef SessionSupportTests * @type {Object} - * @property {number} timestamp + * @property {number} timestamp * @property {SupportTests} supportTests */ @@ -128,8 +128,8 @@ function setSessionSupportTests( supportTests ) { * @private * * @param {CanvasRenderingContext2D} context 2D Context. - * @param {string} set1 Set of Emoji to test. - * @param {string} set2 Set of Emoji to test. + * @param {string} set1 Set of Emoji to test. + * @param {string} set2 Set of Emoji to test. * * @return {boolean} True if the two sets render the same. */ @@ -178,7 +178,7 @@ function emojiSetsRenderIdentically( context, set1, set2 ) { * @private * * @param {CanvasRenderingContext2D} context 2D Context. - * @param {string} emoji Emoji to test. + * @param {string} emoji Emoji to test. * * @return {boolean} True if the center point is empty. */ @@ -209,10 +209,10 @@ function emojiRendersEmptyCenterPoint( context, emoji ) { * * @private * - * @param {CanvasRenderingContext2D} context 2D Context. - * @param {string} type Whether to test for support of "flag" or "emoji". - * @param {Function} emojiSetsRenderIdentically Reference to emojiSetsRenderIdentically function, needed due to minification. - * @param {Function} emojiRendersEmptyCenterPoint Reference to emojiRendersEmptyCenterPoint function, needed due to minification. + * @param {CanvasRenderingContext2D} context 2D Context. + * @param {string} type Whether to test for support of "flag" or "emoji". + * @param {Function} emojiSetsRenderIdentically Reference to emojiSetsRenderIdentically function, needed due to minification. + * @param {Function} emojiRendersEmptyCenterPoint Reference to emojiRendersEmptyCenterPoint function, needed due to minification. * * @return {boolean} True if the browser can render emoji, false if it cannot. */ @@ -302,9 +302,9 @@ function browserSupportsEmoji( context, type, emojiSetsRenderIdentically, emojiR * * @private * - * @param {string[]} tests Tests. - * @param {Function} browserSupportsEmoji Reference to browserSupportsEmoji function, needed due to minification. - * @param {Function} emojiSetsRenderIdentically Reference to emojiSetsRenderIdentically function, needed due to minification. + * @param {string[]} tests Tests. + * @param {Function} browserSupportsEmoji Reference to browserSupportsEmoji function, needed due to minification. + * @param {Function} emojiSetsRenderIdentically Reference to emojiSetsRenderIdentically function, needed due to minification. * @param {Function} emojiRendersEmptyCenterPoint Reference to emojiRendersEmptyCenterPoint function, needed due to minification. * * @return {SupportTests} Support tests. diff --git a/src/js/_enqueues/lib/image-edit.js b/src/js/_enqueues/lib/image-edit.js index 0431551aeb615..3ddc6eded840e 100644 --- a/src/js/_enqueues/lib/image-edit.js +++ b/src/js/_enqueues/lib/image-edit.js @@ -307,8 +307,8 @@ * * @memberof imageEdit * - * @param {Event} event The key or click event. - * @param {HTMLElement} el The current element. + * @param {Event} event The key or click event. + * @param {HTMLElement} el The current element. * * @return {boolean} Always returns false. */ @@ -438,10 +438,10 @@ * * @memberof imageEdit * - * @param {number} postid The current post ID. - * @param {number} x Is 0 when it applies the y-axis - * and 1 when applicable for the x-axis. - * @param {jQuery} el Element. + * @param {number} postid The current post ID. + * @param {number} x Is 0 when it applies the y-axis + * and 1 when applicable for the x-axis. + * @param {jQuery} el Element. * * @return {void} */ @@ -732,8 +732,8 @@ * * @memberof imageEdit * - * @param {number} postid The post ID to get the image from the database. - * @param {string} nonce The nonce to verify the request. + * @param {number} postid The post ID to get the image from the database. + * @param {string} nonce The nonce to verify the request. * * @return {boolean|void} If the actions are successfully saved a response message is shown. * Returns false if there is no image editing history, @@ -801,9 +801,9 @@ * * @memberof imageEdit * - * @param {number} postid The post ID for the image. - * @param {string} nonce The nonce to verify the request. - * @param {Object} view The image editor view to be used for the editing. + * @param {number} postid The post ID for the image. + * @param {string} nonce The nonce to verify the request. + * @param {Object} view The image editor view to be used for the editing. * * @return {void|promise} Either returns void if the button was already activated * or returns an instance of the image editor, wrapped in a promise. @@ -1290,8 +1290,8 @@ * * @memberof imageEdit * - * @param {number} postid The post ID. - * @param {string} nonce The nonce. + * @param {number} postid The post ID. + * @param {string} nonce The nonce. * * @return {void|false} Returns false if the undo button is disabled. */ @@ -1448,9 +1448,9 @@ * * @memberof imageEdit * - * @param {number} postid The post ID. - * @param {number} n The ratio to set. - * @param {jQuery} el The element containing the values. + * @param {number} postid The post ID. + * @param {number} n The ratio to set. + * @param {jQuery} el The element containing the values. * * @return {void} */ diff --git a/src/js/_enqueues/lib/lists.js b/src/js/_enqueues/lib/lists.js index 44e71a84ed488..deb1814bf9214 100644 --- a/src/js/_enqueues/lib/lists.js +++ b/src/js/_enqueues/lib/lists.js @@ -226,7 +226,7 @@ wpList = { * data[2] - ID of the parent element of all inputs necessary for the request. * data[3] - Hex color to be used in this request. If data[0] is 'dim', dim class. * data[4] - Additional arguments in query syntax that are added to the request. Example: 'post_id=1234'. - * If data[0] is 'dim', dim add color. + * If data[0] is 'dim', dim add color. * data[5] - Only available if data[0] is 'dim', dim delete color. * data[6] - Only available if data[0] is 'dim', additional arguments in query syntax that are added to the request. * diff --git a/src/js/_enqueues/lib/pointer.js b/src/js/_enqueues/lib/pointer.js index d946d6c015121..7e63d0e009b53 100644 --- a/src/js/_enqueues/lib/pointer.js +++ b/src/js/_enqueues/lib/pointer.js @@ -74,7 +74,7 @@ * There are 4 special values that do something extra: * * - `document` will transfer the pointer to the body of the new document - * specified by the value. + * specified by the value. * - `pointerClass` will change the class of the pointer element. * - `position` will reposition the pointer. * - `content` will update the content of the pointer. diff --git a/src/js/_enqueues/lib/quicktags.js b/src/js/_enqueues/lib/quicktags.js index bdb978750e549..ffdbfaeef7349 100644 --- a/src/js/_enqueues/lib/quicktags.js +++ b/src/js/_enqueues/lib/quicktags.js @@ -333,12 +333,12 @@ window.edToolbar = function(){}; * use add_action( 'admin_print_footer_scripts', 'output_my_js', 100 ) or add_action( 'wp_footer', 'output_my_js', 100 ) * * Minimum required to add a button that calls an external function: - * QTags.addButton( 'my_id', 'my button', my_callback ); - * function my_callback() { alert('yeah!'); } + * QTags.addButton( 'my_id', 'my button', my_callback ); + * function my_callback() { alert('yeah!'); } * * Minimum required to add a button that inserts a tag: - * QTags.addButton( 'my_id', 'my button', '', '' ); - * QTags.addButton( 'my_id2', 'my button', '
' ); + * 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="..." diff --git a/src/js/_enqueues/lib/user-suggest.js b/src/js/_enqueues/lib/user-suggest.js index f05b7ffa8892f..fc58ac4ef0044 100644 --- a/src/js/_enqueues/lib/user-suggest.js +++ b/src/js/_enqueues/lib/user-suggest.js @@ -34,11 +34,11 @@ * * Optional data-attributes: * - data-autocomplete-type (add, search) - * The action that is going to be performed: search for existing users - * or add a new one. Default: add + * The action that is going to be performed: search for existing users + * or add a new one. Default: add * - data-autocomplete-field (user_login, user_email) - * The field that is returned as the value for the suggestion. - * Default: user_login + * The field that is returned as the value for the suggestion. + * Default: user_login * * @see wp-admin/includes/admin-actions.php:wp_ajax_autocomplete_user() */ diff --git a/src/js/_enqueues/wp/api.js b/src/js/_enqueues/wp/api.js index b15a74628a92c..c91558b20a200 100644 --- a/src/js/_enqueues/wp/api.js +++ b/src/js/_enqueues/wp/api.js @@ -206,8 +206,8 @@ /** * Extract a route part based on negative index. * - * @param {string} route The endpoint route. - * @param {number} part The number of parts from the end of the route to retrieve. Default 1. + * @param {string} route The endpoint route. + * @param {number} part The number of parts from the end of the route to retrieve. Default 1. * 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. @@ -313,7 +313,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. + * @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 ) { @@ -858,9 +858,8 @@ initialize: function() { /** - * Types that don't support trashing require passing ?force=true to delete. - * - */ + * Types that don't support trashing require passing ?force=true to delete. + */ if ( -1 === _.indexOf( trashableTypes, this.name ) ) { this.requireForceForDelete = true; } diff --git a/src/js/_enqueues/wp/backbone.js b/src/js/_enqueues/wp/backbone.js index 4fd194f5737d5..2c8e62d23cca3 100644 --- a/src/js/_enqueues/wp/backbone.js +++ b/src/js/_enqueues/wp/backbone.js @@ -284,7 +284,7 @@ window.wp = window.wp || {}; * @since 3.5.0 * * @return {wp.Backbone.Subviews} The current Subviews instance. - */ + */ render: function() { var options = { ready: this._isReady() @@ -314,7 +314,7 @@ window.wp = window.wp || {}; * the master views' parent. * * @return {wp.Backbone.Subviews} The current Subviews instance. - */ + */ remove: function( options ) { if ( ! options || ! options.silent ) { if ( this.parent && this.parent.views ) @@ -338,7 +338,7 @@ window.wp = window.wp || {}; * @since 3.5.0 * * @param {string} $target Selector where to put the elements. - * @param {*} els HTML or elements to put into the selector's HTML. + * @param {*} els HTML or elements to put into the selector's HTML. * * @return {wp.Backbone.Subviews} The current Subviews instance. */ diff --git a/src/js/_enqueues/wp/code-editor.js b/src/js/_enqueues/wp/code-editor.js index a40a943fed4ad..18451a0a7881e 100644 --- a/src/js/_enqueues/wp/code-editor.js +++ b/src/js/_enqueues/wp/code-editor.js @@ -19,89 +19,89 @@ if ( 'undefined' === typeof window.wp.codeEditor ) { /** * @typedef {Object} CodeMirrorState - * @property {boolean} [completionActive] - Whether completion is active. - * @property {boolean} [focused] - Whether the editor is focused. + * @property {boolean} [completionActive] Whether completion is active. + * @property {boolean} [focused] Whether the editor is focused. */ /** * @typedef {import('codemirror').EditorFromTextArea & { - * options: import('codemirror').EditorConfiguration, - * performLint?: () => void, - * showHint?: (options: import('codemirror').ShowHintOptions) => void, - * state: CodeMirrorState + * options: import('codemirror').EditorConfiguration, + * performLint?: () => void, + * showHint?: (options: import('codemirror').ShowHintOptions) => void, + * state: CodeMirrorState * }} CodeMirrorEditor */ /** * @typedef {Object} LintAnnotation - * @property {string} message - Message. - * @property {'error'|'warning'} severity - Severity. - * @property {import('codemirror').Position} from - From position. - * @property {import('codemirror').Position} to - To position. + * @property {string} message Message. + * @property {'error'|'warning'} severity Severity. + * @property {import('codemirror').Position} from From position. + * @property {import('codemirror').Position} to To position. */ /** * @typedef {Object} CodeMirrorTokenState - * @property {Object} [htmlState] - HTML state. - * @property {string} [htmlState.tagName] - Tag name. - * @property {CodeMirrorTokenState} [curState] - Current state. + * @property {Object} [htmlState] HTML state. + * @property {string} [htmlState.tagName] Tag name. + * @property {CodeMirrorTokenState} [curState] Current state. */ /** * @typedef {import('codemirror').EditorConfiguration & { - * lint?: boolean | CombinedLintOptions, - * autoCloseBrackets?: boolean, - * matchBrackets?: boolean, - * continueComments?: boolean, - * styleActiveLine?: boolean + * lint?: boolean | CombinedLintOptions, + * autoCloseBrackets?: boolean, + * matchBrackets?: boolean, + * continueComments?: boolean, + * styleActiveLine?: boolean * }} CodeMirrorSettings */ /** * @typedef {Object} CSSLintRules - * @property {boolean} [errors] - Errors. - * @property {boolean} [box-model] - Box model rules. - * @property {boolean} [display-property-grouping] - Display property grouping rules. - * @property {boolean} [duplicate-properties] - Duplicate properties rules. - * @property {boolean} [known-properties] - Known properties rules. - * @property {boolean} [outline-none] - Outline none rules. + * @property {boolean} [errors] Errors. + * @property {boolean} [box-model] Box model rules. + * @property {boolean} [display-property-grouping] Display property grouping rules. + * @property {boolean} [duplicate-properties] Duplicate properties rules. + * @property {boolean} [known-properties] Known properties rules. + * @property {boolean} [outline-none] Outline none rules. */ /** * @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. - * @property {boolean} [curly] - Whether to require curly braces. - * @property {boolean} [eqeqeq] - Whether to require === and !==. - * @property {boolean} [eqnull] - Whether to allow == null. - * @property {boolean} [expr] - Whether to allow expressions. - * @property {boolean} [immed] - Whether to require immediate function invocation. - * @property {boolean} [noarg] - Whether to prohibit arguments.caller/callee. - * @property {boolean} [nonbsp] - Whether to prohibit non-breaking spaces. - * @property {string} [quotmark] - Quote mark preference. - * @property {boolean} [undef] - Whether to prohibit undefined variables. - * @property {boolean} [unused] - Whether to prohibit unused variables. - * @property {boolean} [browser] - Whether to enable browser globals. - * @property {Record} [globals] - Global variables. + * @property {number} [esversion] ECMAScript version. + * @property {boolean} [module] Whether to use modules. + * @property {boolean} [boss] Whether to allow assignments in control expressions. + * @property {boolean} [curly] Whether to require curly braces. + * @property {boolean} [eqeqeq] Whether to require === and !==. + * @property {boolean} [eqnull] Whether to allow == null. + * @property {boolean} [expr] Whether to allow expressions. + * @property {boolean} [immed] Whether to require immediate function invocation. + * @property {boolean} [noarg] Whether to prohibit arguments.caller/callee. + * @property {boolean} [nonbsp] Whether to prohibit non-breaking spaces. + * @property {string} [quotmark] Quote mark preference. + * @property {boolean} [undef] Whether to prohibit undefined variables. + * @property {boolean} [unused] Whether to prohibit unused variables. + * @property {boolean} [browser] Whether to enable browser globals. + * @property {Record} [globals] Global variables. */ /** * @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. - * @property {boolean} [doctype-first] - Doctype first rules. - * @property {boolean} [tag-pair] - Tag pair rules. - * @property {boolean} [spec-char-escape] - Spec char escape rules. - * @property {boolean} [id-unique] - ID unique rules. - * @property {boolean} [src-not-empty] - Src not empty rules. - * @property {boolean} [attr-no-duplication] - Attribute no duplication rules. - * @property {boolean} [alt-require] - Alt require rules. - * @property {string} [space-tab-mixed-disabled] - Space tab mixed disabled rules. - * @property {boolean} [attr-unsafe-chars] - Attribute unsafe chars rules. - * @property {JSHintRules} [jshint] - JSHint rules. - * @property {CSSLintRules} [csslint] - CSSLint rules. + * @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. + * @property {boolean} [doctype-first] Doctype first rules. + * @property {boolean} [tag-pair] Tag pair rules. + * @property {boolean} [spec-char-escape] Spec char escape rules. + * @property {boolean} [id-unique] ID unique rules. + * @property {boolean} [src-not-empty] Src not empty rules. + * @property {boolean} [attr-no-duplication] Attribute no duplication rules. + * @property {boolean} [alt-require] Alt require rules. + * @property {string} [space-tab-mixed-disabled] Space tab mixed disabled rules. + * @property {boolean} [attr-unsafe-chars] Attribute unsafe chars rules. + * @property {JSHintRules} [jshint] JSHint rules. + * @property {CSSLintRules} [csslint] CSSLint rules. */ /** @@ -109,15 +109,15 @@ if ( 'undefined' === typeof window.wp.codeEditor ) { * * @typedef {Object} CodeEditorSettings * - * @property {CodeMirrorSettings} [codemirror] - CodeMirror settings. - * @property {CSSLintRules} [csslint] - CSSLint rules. - * @property {JSHintRules} [jshint] - JSHint rules. - * @property {HTMLHintRules} [htmlhint] - HTMLHint rules. + * @property {CodeMirrorSettings} [codemirror] CodeMirror settings. + * @property {CSSLintRules} [csslint] CSSLint rules. + * @property {JSHintRules} [jshint] JSHint rules. + * @property {HTMLHintRules} [htmlhint] HTMLHint rules. * - * @property {(codemirror: CodeMirrorEditor, event: KeyboardEvent|JQuery.KeyDownEvent) => void} [onTabNext] - Callback to handle tabbing to the next tabbable element. - * @property {(codemirror: CodeMirrorEditor, event: KeyboardEvent|JQuery.KeyDownEvent) => void} [onTabPrevious] - Callback to handle tabbing to the previous tabbable element. - * @property {(errorAnnotations: LintAnnotation[], annotations: LintAnnotation[], annotationsSorted: LintAnnotation[], cm: CodeMirrorEditor) => void} [onChangeLintingErrors] - Callback for when the linting errors have changed. - * @property {(errorAnnotations: LintAnnotation[], editor: CodeMirrorEditor) => void} [onUpdateErrorNotice] - Callback for when error notice should be displayed. + * @property {(codemirror: CodeMirrorEditor, event: KeyboardEvent|JQuery.KeyDownEvent) => void} [onTabNext] Callback to handle tabbing to the next tabbable element. + * @property {(codemirror: CodeMirrorEditor, event: KeyboardEvent|JQuery.KeyDownEvent) => void} [onTabPrevious] Callback to handle tabbing to the previous tabbable element. + * @property {(errorAnnotations: LintAnnotation[], annotations: LintAnnotation[], annotationsSorted: LintAnnotation[], cm: CodeMirrorEditor) => void} [onChangeLintingErrors] Callback for when the linting errors have changed. + * @property {(errorAnnotations: LintAnnotation[], editor: CodeMirrorEditor) => void} [onUpdateErrorNotice] Callback for when error notice should be displayed. */ /** @@ -126,15 +126,15 @@ if ( 'undefined' === typeof window.wp.codeEditor ) { /** * @typedef {Object} CodeEditorInstance - * @property {CodeEditorSettings} settings - The code editor settings. - * @property {CodeMirrorEditor} codemirror - The CodeMirror instance. - * @property {() => void} updateErrorNotice - Force update the error notice. + * @property {CodeEditorSettings} settings The code editor settings. + * @property {CodeMirrorEditor} codemirror The CodeMirror instance. + * @property {() => void} updateErrorNotice Force update the error notice. */ /** * @typedef {Object} WpCodeEditor - * @property {CodeEditorSettings} defaultSettings - Default settings. - * @property {(textarea: string|JQuery|Element, settings?: CodeEditorSettings) => CodeEditorInstance} initialize - Initialize. + * @property {CodeEditorSettings} defaultSettings Default settings. + * @property {(textarea: string|JQuery|Element, settings?: CodeEditorSettings) => CodeEditorInstance} initialize Initialize. */ /** @@ -166,7 +166,7 @@ if ( 'undefined' === typeof window.wp.codeEditor ) { /** * Configures linting. * - * @param {CodeEditorSettings} settings - Code editor settings. + * @param {CodeEditorSettings} settings Code editor settings. * * @return {LintingController} Linting controller. */ @@ -180,7 +180,7 @@ if ( 'undefined' === typeof window.wp.codeEditor ) { /** * Call the onUpdateErrorNotice if there are new errors to show. * - * @param {import('codemirror').Editor} editor - Editor. + * @param {import('codemirror').Editor} editor Editor. * @return {void} */ function updateErrorNotice( editor ) { @@ -237,9 +237,9 @@ if ( 'undefined' === typeof window.wp.codeEditor ) { /** * Wraps the onUpdateLinting event to filter errors, detect state changes, and manage error notice visibility. * - * @param {LintAnnotation[]} annotations - Annotations. - * @param {LintAnnotation[]} annotationsSorted - Sorted annotations. - * @param {CodeMirrorEditor} cm - Editor. + * @param {LintAnnotation[]} annotations Annotations. + * @param {LintAnnotation[]} annotationsSorted Sorted annotations. + * @param {CodeMirrorEditor} cm Editor. */ return function( annotations, annotationsSorted, cm ) { const errorAnnotations = annotations.filter( function( annotation ) { @@ -281,7 +281,7 @@ if ( 'undefined' === typeof window.wp.codeEditor ) { /** * Initializes the CodeMirror editor. * - * @param {CodeMirrorEditor} editor - Editor instance. + * @param {CodeMirrorEditor} editor Editor instance. * @return {void} */ init: function( editor ) { @@ -349,7 +349,7 @@ if ( 'undefined' === typeof window.wp.codeEditor ) { } ); }, /** - * @param {CodeMirrorEditor} editor - Editor instance. + * @param {CodeMirrorEditor} editor Editor instance. * @return {void} */ updateErrorNotice, @@ -359,8 +359,8 @@ if ( 'undefined' === typeof window.wp.codeEditor ) { /** * Configure tabbing. * - * @param {CodeMirrorEditor} codemirror - Editor. - * @param {CodeEditorSettings} settings - Code editor settings. + * @param {CodeMirrorEditor} codemirror Editor. + * @param {CodeEditorSettings} settings Code editor settings. * * @return {void} */ @@ -399,9 +399,9 @@ if ( 'undefined' === typeof window.wp.codeEditor ) { /** * @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. + * @property {() => CombinedLintOptions|false} getLintOptions Get lint options. + * @property {(editor: CodeMirrorEditor) => void} init Initialize. + * @property {(editor: import('codemirror').Editor) => void} updateErrorNotice Update error notice. */ /** @@ -409,8 +409,8 @@ if ( 'undefined' === typeof window.wp.codeEditor ) { * * @since 4.9.0 * - * @param {string|JQuery|HTMLElement} textarea - The HTML id, jQuery object, or DOM Element for the textarea that is used for the editor. - * @param {CodeEditorSettings} [settings] - Settings to override defaults. + * @param {string|JQuery|HTMLElement} textarea The HTML id, jQuery object, or DOM Element for the textarea that is used for the editor. + * @param {CodeEditorSettings} [settings] Settings to override defaults. * * @return {CodeEditorInstance} Instance. */ diff --git a/src/js/_enqueues/wp/custom-header.js b/src/js/_enqueues/wp/custom-header.js index 7d4fa98d7cc53..fccab2565b164 100644 --- a/src/js/_enqueues/wp/custom-header.js +++ b/src/js/_enqueues/wp/custom-header.js @@ -19,7 +19,7 @@ * Trigger an event. * * @param {Element} target HTML element to dispatch the event on. - * @param {string} name Event name. + * @param {string} name Event name. */ function trigger( target, name ) { var evt; diff --git a/src/js/_enqueues/wp/customize/base.js b/src/js/_enqueues/wp/customize/base.js index 2b694b9a021c1..44e23ae35740d 100644 --- a/src/js/_enqueues/wp/customize/base.js +++ b/src/js/_enqueues/wp/customize/base.js @@ -568,7 +568,7 @@ window.wp = window.wp || {}; * when( ids*, [callback] ); * * For example: - * when( id1, id2, id3, function( value1, value2, value3 ) {} ); + * when( id1, id2, id3, function( value1, value2, value3 ) {} ); * * @param {...(string|Function)} ids Zero or more IDs of items to wait for, optionally followed by * a callback function to invoke once they are all available. diff --git a/src/js/_enqueues/wp/customize/controls.js b/src/js/_enqueues/wp/customize/controls.js index 94693163c0240..64bfd3fe754be 100644 --- a/src/js/_enqueues/wp/customize/controls.js +++ b/src/js/_enqueues/wp/customize/controls.js @@ -3101,7 +3101,7 @@ api.ThemesPanel = api.Panel.extend(/** @lends wp.customize.ThemesPanel.prototype */{ /** - * Class wp.customize.ThemesPanel. + * Class wp.customize.ThemesPanel. * * Custom section for themes that displays without the customize preview. * diff --git a/src/js/_enqueues/wp/customize/loader.js b/src/js/_enqueues/wp/customize/loader.js index 152d5d48dc780..0f053f4c69505 100644 --- a/src/js/_enqueues/wp/customize/loader.js +++ b/src/js/_enqueues/wp/customize/loader.js @@ -33,7 +33,7 @@ window.wp = window.wp || {}; * By default, any element in the body with the load-customize class will open * an iframe overlay with the URL specified. * - * e.g. Open Customizer + * e.g. Open Customizer * * @memberOf wp.customize * diff --git a/src/js/_enqueues/wp/dashboard.js b/src/js/_enqueues/wp/dashboard.js index 595133d790782..1fbfdec57a508 100644 --- a/src/js/_enqueues/wp/dashboard.js +++ b/src/js/_enqueues/wp/dashboard.js @@ -67,7 +67,7 @@ jQuery( function($) { * @type {string[]} * * @global - */ + */ window.ajaxWidgets = ['dashboard_primary']; /** @@ -85,7 +85,7 @@ jQuery( function($) { /** * Fetch the latest representation of the widget via Ajax and show it. * - * @param {number} i Number of half-seconds to use as the timeout. + * @param {number} i Number of half-seconds to use as the timeout. * @param {string} id ID of the element which is going to be checked for changes. * * @return {void} @@ -163,7 +163,7 @@ jQuery( function($) { * Highlights the latest post for one second. * * @return {void} - */ + */ function highlightLatestPost () { var latestPost = $( '.drafts ul li' ) .first(), errorNotice = $( '#quick-press .notice-error' ); @@ -835,7 +835,7 @@ jQuery( function( $ ) { * @deprecated 5.6.0 * * @type {Object} -*/ + */ window.communityEventsData.l10n = window.communityEventsData.l10n || { enter_closest_city: '', error_occurred_please_try_again: '', diff --git a/src/js/_enqueues/wp/editor/base.js b/src/js/_enqueues/wp/editor/base.js index 0c3485ca7d661..d7618acdafe3d 100644 --- a/src/js/_enqueues/wp/editor/base.js +++ b/src/js/_enqueues/wp/editor/base.js @@ -78,7 +78,7 @@ window.wp = window.wp || {}; * * @memberof switchEditors * - * @param {string} id The id of the editor you want to change the editor mode for. Default: `content`. + * @param {string} id The id of the editor you want to change the editor mode for. Default: `content`. * @param {string} mode The mode you want to switch to. Default: `toggle`. * @return {void} */ @@ -201,7 +201,7 @@ window.wp = window.wp || {}; * the tag type, if it is a closing tag and check if the HTML tag is inside a shortcode tag, * e.g. `[caption]..`. * - * @param {string} content The test content where the cursor is. + * @param {string} content The test content where the cursor is. * @param {number} cursorPosition The cursor position inside the content. * * @return {(null|Object)} Null if cursor is not in a tag, Object if the cursor is inside a tag. @@ -246,8 +246,8 @@ window.wp = window.wp || {}; * Moving the selection to before or after the short code is better, since it allows to select * something, instead of just losing focus and going to the start of the content. * - * @param {string} content The text content to check against. - * @param {number} cursorPosition The cursor position to check. + * @param {string} content The text content to check against. + * @param {number} cursorPosition The cursor position to check. * * @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. @@ -372,7 +372,7 @@ window.wp = window.wp || {}; * * Using DomQuery syntax to create it, since it's used as both text and as a DOM element. * - * @param {Object} domLib DOM library instance. + * @param {Object} domLib DOM library instance. * @param {string} content The content to insert into the cursor marker element. * @return {Object} The cursor marker element. */ @@ -395,7 +395,7 @@ window.wp = window.wp || {}; * * @link getShortcodeWrapperInfo * - * @param {string} content Textarea content that the cursors are in + * @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}} Adjusted cursor positions with `cursorStart` and `cursorEnd` properties. @@ -585,7 +585,7 @@ window.wp = window.wp || {}; * I order to achieve the proper positioning, the editor media bar and toolbar are subtracted * from the window height, to get the proper viewport window, that the user sees. * - * @param {Object} editor TinyMCE editor instance. + * @param {Object} editor TinyMCE editor instance. * @param {Object} element HTMLElement that should be scrolled into view. */ function scrollVisualModeToStartElement( editor, element ) { @@ -825,7 +825,7 @@ window.wp = window.wp || {}; * For `selection` parameter: * @link findBookmarkedPosition * - * @param {Object} editor TinyMCE's editor instance. + * @param {Object} editor TinyMCE's editor instance. * @param {Object} selection Selection data. */ function selectTextInTextArea( editor, selection ) { @@ -1224,9 +1224,27 @@ window.wp = window.wp || {}; * * @since 4.8.0 * - * @param {string} id The HTML id of the textarea that is used for the editor. - * Has to be jQuery compliant. No brackets, special chars, etc. - * @param {Object} settings Example: + * @param {string} id The HTML id of the textarea that is used for the editor. + * Has to be jQuery compliant. No brackets, special chars, etc. + * @param {Object} settings The settings for initializing the editor. + * + * @example + * ```javascript + * settings = { + * // See https://www.tinymce.com/docs/configure/integration-and-setup/. + * // Alternatively set to `true` to use the defaults. + * tinymce: { + * setup: function( editor ) { + * console.log( 'Editor initialized', editor ); + * } + * } + * + * // Alternatively set to `true` to use the defaults. + * quicktags: { + * buttons: 'strong,em,link' + * } + * } + * * settings = { * // See https://www.tinymce.com/docs/configure/integration-and-setup/. * // Alternatively set to `true` to use the defaults. @@ -1241,6 +1259,7 @@ window.wp = window.wp || {}; * buttons: 'strong,em,link' * } * } + * ``` */ wp.editor.initialize = function( id, settings ) { var init; diff --git a/src/js/_enqueues/wp/editor/dfw.js b/src/js/_enqueues/wp/editor/dfw.js index d6a563e8f7872..ff640ca9dd121 100644 --- a/src/js/_enqueues/wp/editor/dfw.js +++ b/src/js/_enqueues/wp/editor/dfw.js @@ -173,7 +173,7 @@ * * @since 4.0.0 * - * @param {event} event The TinyMCE editor init event. + * @param {event} event The TinyMCE editor init event. * @param {Object} editor The editor to bind the vents on. * * @return {void} @@ -1473,7 +1473,7 @@ * * @since 4.1.0 * - * @param {event} event The TinyMCE editor setup event. + * @param {event} event The TinyMCE editor setup event. * @param {Object} editor The editor to add the button to. * * @return {void} @@ -1522,7 +1522,7 @@ * * @since 4.1.0 * - * @param {event} event The TinyMCE editor init event. + * @param {event} event The TinyMCE editor init event. * @param {Object} editor The editor to bind events on. * * @return {void} @@ -1581,11 +1581,11 @@ } ); /** - * Binds events on quicktags init. + * Binds events on quicktags init. * * @since 4.1.0 * - * @param {event} event The quicktags init event. + * @param {event} event The quicktags init event. * @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 5522fb824a38c..1f34177c3362f 100644 --- a/src/js/_enqueues/wp/embed.js +++ b/src/js/_enqueues/wp/embed.js @@ -1,7 +1,7 @@ /** * WordPress inline HTML embed * - * @param {Window} window The global window object. + * @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 diff --git a/src/js/_enqueues/wp/emoji.js b/src/js/_enqueues/wp/emoji.js index 1c134e2dfef85..274868f52d859 100644 --- a/src/js/_enqueues/wp/emoji.js +++ b/src/js/_enqueues/wp/emoji.js @@ -2,7 +2,7 @@ * 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 {Window} window The global window object. * @param {Object} settings The settings object. * @output wp-includes/js/wp-emoji.js */ @@ -190,7 +190,7 @@ * * - When passed an element the emoji characters are replaced inline. * - When passed a string the emoji characters are replaced and the result is - * returned. + * returned. * * @since 4.2.0 * diff --git a/src/js/_enqueues/wp/heartbeat.js b/src/js/_enqueues/wp/heartbeat.js index e816959bda1bf..6f89e1db47b6c 100644 --- a/src/js/_enqueues/wp/heartbeat.js +++ b/src/js/_enqueues/wp/heartbeat.js @@ -790,12 +790,17 @@ /** * Enqueues data to send with the next XHR. * - * As the data is send asynchronously, this function doesn't return the XHR + * As the data is sent asynchronously, this function doesn't return the XHR * response. To see the response, use the custom jQuery event 'heartbeat-tick' - * on the document, example: + * on the document. + * + * @example + * ```javascript * $(document).on( 'heartbeat-tick.myname', function( event, data, textStatus, jqXHR ) { * // code * }); + * ``` + * * If the same 'handle' is used more than once, the data is not overwritten when * the third argument is 'true'. Use `wp.heartbeat.isQueued('handle')` to see if * any data is already queued for that handle. diff --git a/src/js/_enqueues/wp/media/audiovideo.js b/src/js/_enqueues/wp/media/audiovideo.js index 485a1699726bf..d330831c490eb 100644 --- a/src/js/_enqueues/wp/media/audiovideo.js +++ b/src/js/_enqueues/wp/media/audiovideo.js @@ -197,8 +197,8 @@ wp.media.audio = { /** * Shortcode modeling for video. * - * `edit()` prepares the shortcode for the media modal. - * `shortcode()` builds the new shortcode after update. + * `edit()` prepares the shortcode for the media modal. + * `shortcode()` builds the new shortcode after update. * * @since 4.2.0 * diff --git a/src/js/_enqueues/wp/media/editor.js b/src/js/_enqueues/wp/media/editor.js index b6357520db557..3c0678c38e6d6 100644 --- a/src/js/_enqueues/wp/media/editor.js +++ b/src/js/_enqueues/wp/media/editor.js @@ -20,11 +20,11 @@ /** * A helper mixin function to avoid truthy and falsey values being - * passed as an input that expects booleans. If key is undefined in the map, - * but has a default value, set it. + * passed as an input that expects booleans. If key is undefined in the map, + * but has a default value, set it. * * @param {Object} attrs Map of props from a shortcode or settings. - * @param {string} key The key within the passed map to check for a value. + * @param {string} key The key within the passed map to check for a value. * @return {mixed|undefined} The original or coerced value of key within attrs. */ wp.media.coerce = function ( attrs, key ) { @@ -111,7 +111,7 @@ /** * Create link markup that is suitable for passing to the editor * - * @param {Object} props Attachment details (align, link, size, etc). + * @param {Object} props Attachment details (align, link, size, etc). * @param {Object} attachment The attachment object, media version of Post. * @return {string} The link markup */ @@ -137,7 +137,7 @@ /** * Create an Audio shortcode string that is suitable for passing to the editor * - * @param {Object} props Attachment details (align, link, size, etc). + * @param {Object} props Attachment details (align, link, size, etc). * @param {Object} attachment The attachment object, media version of Post. * @return {string} The audio shortcode */ @@ -147,7 +147,7 @@ /** * Create a Video shortcode string that is suitable for passing to the editor * - * @param {Object} props Attachment details (align, link, size, etc). + * @param {Object} props Attachment details (align, link, size, etc). * @param {Object} attachment The attachment object, media version of Post. * @return {string} The video shortcode */ @@ -159,8 +159,8 @@ * * @access private * - * @param {string} type The shortcode tag name: 'audio' or 'video'. - * @param {Object} props Attachment details (align, link, size, etc). + * @param {string} type The shortcode tag name: 'audio' or 'video'. + * @param {Object} props Attachment details (align, link, size, etc). * @param {Object} attachment The attachment object, media version of Post. * @return {string} The media shortcode */ @@ -206,9 +206,9 @@ }, /** * Create image markup, optionally with a link and/or wrapped in a caption shortcode, - * that is suitable for passing to the editor + * that is suitable for passing to the editor * - * @param {Object} props Attachment details (align, link, size, etc). + * @param {Object} props Attachment details (align, link, size, etc). * @param {Object} attachment The attachment object, media version of Post. * @return {string} The image markup. */ @@ -418,9 +418,9 @@ * Triggered when clicking 'Insert {label}' or 'Update {label}' * * @param {wp.media.model.Attachments} attachments A Backbone.Collection containing - * the media items belonging to a collection. - * The query[ this.tag ] property is a Backbone.Model - * containing the 'props' for the collection. + * 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} A wp.shortcode instance representing the collection. */ shortcode: function( attachments ) { @@ -485,10 +485,10 @@ }, /** * Triggered when double-clicking a collection shortcode placeholder - * in the editor + * in the editor * * @param {string} content Content that is searched for possible - * shortcode markup matching the passed tag name, + * shortcode markup matching the passed tag name, * * @this wp.media.{prop} * @@ -689,7 +689,7 @@ }, /** * 'select' callback for Featured Image workflow, triggered when - * the 'Set Featured Image' button is clicked in the media modal. + * the 'Set Featured Image' button is clicked in the media modal. * * @this wp.media.controller.FeaturedImage */ @@ -784,7 +784,7 @@ /** * Setup 'workflow' and add to the 'workflows' cache. 'open' can - * subsequently be called upon it. + * subsequently be called upon it. * * @param {string} id A slug used to identify the workflow. * @param {Object} [options={}] The options for the media workflow. @@ -943,9 +943,9 @@ send: { /** * Called when sending an attachment to the editor - * from the medial modal. + * from the medial modal. * - * @param {Object} props Attachment details (align, link, size, etc). + * @param {Object} props Attachment details (align, link, size, etc). * @param {Object} attachment The attachment object, media version of Post. * @return {Promise} A promise that resolves when the attachment has been sent to the editor. */ diff --git a/src/js/_enqueues/wp/password-strength-meter.js b/src/js/_enqueues/wp/password-strength-meter.js index 6aba8749adffa..3ed6d48d5ef25 100644 --- a/src/js/_enqueues/wp/password-strength-meter.js +++ b/src/js/_enqueues/wp/password-strength-meter.js @@ -26,10 +26,10 @@ window.wp = window.wp || {}; * * @since 3.7.0 * - * @param {string} password1 The subject password. + * @param {string} password1 The subject password. * @param {Array} disallowedList An array of words that will lower the entropy of - * the password. - * @param {string} password2 The password confirmation. + * the password. + * @param {string} password2 The password confirmation. * * @return {number} The password strength score. */ diff --git a/src/js/_enqueues/wp/sanitize.js b/src/js/_enqueues/wp/sanitize.js index c5c97f6c37564..f67a8fd25a97f 100644 --- a/src/js/_enqueues/wp/sanitize.js +++ b/src/js/_enqueues/wp/sanitize.js @@ -19,7 +19,7 @@ /** * Strip HTML tags. * - * @param {string} text - Text to strip the HTML tags from. + * @param {string} text Text to strip the HTML tags from. * * @return {string} Stripped text. */ @@ -52,7 +52,7 @@ /** * Strip HTML tags and convert HTML entities. * - * @param {string} text - Text to strip tags and convert HTML entities. + * @param {string} text Text to strip tags and convert HTML entities. * * @return {string} Sanitized text. */ diff --git a/src/js/_enqueues/wp/theme-plugin-editor.js b/src/js/_enqueues/wp/theme-plugin-editor.js index 74e0634f94e45..72a4471a93994 100644 --- a/src/js/_enqueues/wp/theme-plugin-editor.js +++ b/src/js/_enqueues/wp/theme-plugin-editor.js @@ -29,9 +29,9 @@ wp.themePluginEditor = (function( $ ) { * * @since 4.9.0 * - * @param {jQuery} form - Form element. - * @param {Object} settings - Settings. - * @param {Object|boolean} settings.codeEditor - Code editor settings (or `false` if syntax highlighting is disabled). + * @param {jQuery} form Form element. + * @param {Object} settings Settings. + * @param {Object|boolean} settings.codeEditor Code editor settings (or `false` if syntax highlighting is disabled). * @return {void} */ component.init = function init( form, settings ) { @@ -187,7 +187,7 @@ wp.themePluginEditor = (function( $ ) { * Submit file via Ajax. * * @since 4.9.0 - * @param {jQuery.Event} event - Event. + * @param {jQuery.Event} event Event. * @return {void} */ component.submit = function( event ) { @@ -273,12 +273,12 @@ wp.themePluginEditor = (function( $ ) { * * @since 4.9.0 * - * @param {Object} notice - Notice. - * @param {string} notice.code - Code. - * @param {string} notice.type - Type. - * @param {string} notice.message - Message. - * @param {boolean} [notice.dismissible=false] - Dismissible. - * @param {Function} [notice.onDismiss] - Callback for when a user dismisses the notice. + * @param {Object} notice Notice. + * @param {string} notice.code Code. + * @param {string} notice.type Type. + * @param {string} notice.message Message. + * @param {boolean} [notice.dismissible=false] Dismissible. + * @param {Function} [notice.onDismiss] Callback for when a user dismisses the notice. * @return {jQuery} Notice element. */ component.addNotice = function( notice ) { @@ -314,7 +314,7 @@ wp.themePluginEditor = (function( $ ) { * * @since 4.9.0 * - * @param {string} code - Notice code. + * @param {string} code Notice code. * @return {boolean} Whether a notice was removed. */ component.removeNotice = function( code ) { @@ -366,7 +366,7 @@ wp.themePluginEditor = (function( $ ) { * * @since 4.9.0 * - * @param {Array} errors - List of linting errors. + * @param {Array} errors List of linting errors. * @return {void} */ codeEditorSettings.onChangeLintingErrors = function( errors ) { @@ -383,7 +383,7 @@ wp.themePluginEditor = (function( $ ) { * * @since 4.9.0 * - * @param {Array} errorAnnotations - Error annotations. + * @param {Array} errorAnnotations Error annotations. * @return {void} */ codeEditorSettings.onUpdateErrorNotice = function onUpdateErrorNotice( errorAnnotations ) { @@ -491,26 +491,24 @@ wp.themePluginEditor = (function( $ ) { */ var TreeitemLink = (function () { /** - * This content is licensed according to the W3C Software License at - * https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document + * This content is licensed according to the W3C Software License at + * https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document * - * File: TreeitemLink.js + * File: TreeitemLink.js * - * Desc: Treeitem widget that implements ARIA Authoring Practices - * for a tree being used as a file viewer + * Desc: Treeitem widget that implements ARIA Authoring Practices + * for a tree being used as a file viewer * - * Author: Jon Gunderson, Ku Ja Eun and Nicholas Hoyt + * Author: Jon Gunderson, Ku Ja Eun and Nicholas Hoyt */ /** - * @class + * @class * - * @description - * Treeitem object for representing the state and user interactions for a - * treeItem widget + * Treeitem object for representing the state and user interactions for a + * treeItem widget * - * @param node - * An element with the role=tree attribute + * @param node An element with the role=tree attribute */ var TreeitemLink = function (node, treeObj, group) { diff --git a/src/js/_enqueues/wp/theme.js b/src/js/_enqueues/wp/theme.js index 2249495ea4d1b..396fd4e3c9c41 100644 --- a/src/js/_enqueues/wp/theme.js +++ b/src/js/_enqueues/wp/theme.js @@ -1485,8 +1485,8 @@ themes.view.Search = wp.Backbone.View.extend({ * * @since 4.9.0 * - * @param {string} url - URL to navigate to. - * @param {Object} state - State. + * @param {string} url URL to navigate to. + * @param {Object} state State. * @return {void} */ function navigateRouter( url, state ) { diff --git a/src/js/_enqueues/wp/updates.js b/src/js/_enqueues/wp/updates.js index 7c971f4bb7d80..635a32975db48 100644 --- a/src/js/_enqueues/wp/updates.js +++ b/src/js/_enqueues/wp/updates.js @@ -1115,10 +1115,10 @@ * * @since 6.5.0 * - * @param {Object} response Response from the server. - * @param {string} response.slug Slug of the activated plugin. - * @param {string} response.pluginName Name of the activated plugin. - * @param {string} response.plugin The plugin file, relative to the plugins directory. + * @param {Object} response Response from the server. + * @param {string} response.slug Slug of the activated plugin. + * @param {string} response.pluginName Name of the activated plugin. + * @param {string} response.plugin The plugin file, relative to the plugins directory. */ wp.updates.activatePluginSuccess = function( response ) { var $message = $( '.plugin-card-' + response.slug + ', #plugin-information-footer' ).find( '.activating-message' ), diff --git a/src/js/_enqueues/wp/utils/word-count.js b/src/js/_enqueues/wp/utils/word-count.js index 066fc5817b491..4c336582ecf63 100644 --- a/src/js/_enqueues/wp/utils/word-count.js +++ b/src/js/_enqueues/wp/utils/word-count.js @@ -148,8 +148,8 @@ * * @memberof wp.utils.wordcounter * - * @param {string} text Text to count elements in. - * @param {string} type Optional. Specify type to use. + * @param {string} text Text to count elements in. + * @param {string} type Optional. Specify type to use. * * @return {number} The number of items counted. */ diff --git a/src/js/_enqueues/wp/widgets/custom-html.js b/src/js/_enqueues/wp/widgets/custom-html.js index 984233ecddfcb..73faf12af61da 100644 --- a/src/js/_enqueues/wp/widgets/custom-html.js +++ b/src/js/_enqueues/wp/widgets/custom-html.js @@ -42,9 +42,9 @@ wp.customHtmlWidgets = ( function( $ ) { * @augments Backbone.View * @abstract * - * @param {Object} options - Options. - * @param {jQuery} options.el - Control field container element. - * @param {jQuery} options.syncContainer - Container element where fields are synced for the server. + * @param {Object} options Options. + * @param {jQuery} options.el Control field container element. + * @param {jQuery} options.syncContainer Container element where fields are synced for the server. * * @return {void} */ @@ -124,7 +124,7 @@ wp.customHtmlWidgets = ( function( $ ) { /** * Show linting error notice. * - * @param {Array} errorAnnotations - Error annotations. + * @param {Array} errorAnnotations Error annotations. * @return {void} */ updateErrorNotice: function( errorAnnotations ) { @@ -205,7 +205,7 @@ wp.customHtmlWidgets = ( function( $ ) { * * @ignore * - * @param {Array} errorAnnotations - Error notifications. + * @param {Array} errorAnnotations Error notifications. * @return {void} */ onChangeLintingErrors: function onChangeLintingErrors( errorAnnotations ) { @@ -217,7 +217,7 @@ wp.customHtmlWidgets = ( function( $ ) { * * @ignore * - * @param {Array} errorAnnotations - Error annotations. + * @param {Array} errorAnnotations Error annotations. * @return {void} */ onUpdateErrorNotice: function onUpdateErrorNotice( errorAnnotations ) { @@ -287,8 +287,8 @@ wp.customHtmlWidgets = ( function( $ ) { * * @alias wp.customHtmlWidgets.handleWidgetAdded * - * @param {jQuery.Event} event - Event. - * @param {jQuery} widgetContainer - Widget container element. + * @param {jQuery.Event} event Event. + * @param {jQuery} widgetContainer Widget container element. * * @return {void} */ @@ -384,8 +384,8 @@ wp.customHtmlWidgets = ( function( $ ) { * * @alias wp.customHtmlWidgets.handleWidgetUpdated * - * @param {jQuery.Event} event - Event. - * @param {jQuery} widgetContainer - Widget container element. + * @param {jQuery.Event} event Event. + * @param {jQuery} widgetContainer Widget container element. * @return {void} */ component.handleWidgetUpdated = function handleWidgetUpdated( event, widgetContainer ) { @@ -415,7 +415,7 @@ wp.customHtmlWidgets = ( function( $ ) { * * @alias wp.customHtmlWidgets.init * - * @param {Object} settings - Options for code editor, exported from PHP. + * @param {Object} settings Options for code editor, exported from PHP. * * @return {void} */ diff --git a/src/js/_enqueues/wp/widgets/media-audio.js b/src/js/_enqueues/wp/widgets/media-audio.js index a57925364da70..ea85263298ed4 100644 --- a/src/js/_enqueues/wp/widgets/media-audio.js +++ b/src/js/_enqueues/wp/widgets/media-audio.js @@ -69,7 +69,7 @@ /** * Map model props to media frame props. * - * @param {Object} modelProps - Model props. + * @param {Object} modelProps Model props. * @return {Object} Media frame props. */ mapModelToMediaFrameProps: function mapModelToMediaFrameProps( modelProps ) { diff --git a/src/js/_enqueues/wp/widgets/media-gallery.js b/src/js/_enqueues/wp/widgets/media-gallery.js index 497fecd0fbd42..fe9f93cb381db 100644 --- a/src/js/_enqueues/wp/widgets/media-gallery.js +++ b/src/js/_enqueues/wp/widgets/media-gallery.js @@ -84,10 +84,10 @@ * @augments wp.mediaWidgets.MediaWidgetControl * * @since 4.9.0 - * @param {Object} options - Options. - * @param {Backbone.Model} options.model - Model. - * @param {jQuery} options.el - Control field container element. - * @param {jQuery} options.syncContainer - Container element where fields are synced for the server. + * @param {Object} options Options. + * @param {Backbone.Model} options.model Model. + * @param {jQuery} options.el Control field container element. + * @param {jQuery} options.syncContainer Container element where fields are synced for the server. * @return {void} */ initialize: function initialize( options ) { @@ -320,7 +320,7 @@ * Clear the selected attachment when it is deleted in the media select frame. * * @since 4.9.0 - * @param {wp.media.models.Attachment} attachment - Attachment. + * @param {wp.media.models.Attachment} attachment Attachment. * @return {void} */ handleAttachmentDestroy: function handleAttachmentDestroy( attachment ) { diff --git a/src/js/_enqueues/wp/widgets/media-image.js b/src/js/_enqueues/wp/widgets/media-image.js index c16600c022c2f..ff0b996d275ad 100644 --- a/src/js/_enqueues/wp/widgets/media-image.js +++ b/src/js/_enqueues/wp/widgets/media-image.js @@ -137,7 +137,7 @@ * * Prevent the image_title attribute from being initially set when adding an image from the media library. * - * @param {wp.media.view.MediaFrame.Select} mediaFrame - Select frame. + * @param {wp.media.view.MediaFrame.Select} mediaFrame Select frame. * @return {Object} Props. */ getModelPropsFromMediaFrame: function getModelPropsFromMediaFrame( mediaFrame ) { diff --git a/src/js/_enqueues/wp/widgets/media-video.js b/src/js/_enqueues/wp/widgets/media-video.js index 56a8ff1f3d5a4..180797f0ae291 100644 --- a/src/js/_enqueues/wp/widgets/media-video.js +++ b/src/js/_enqueues/wp/widgets/media-video.js @@ -87,7 +87,7 @@ /** * Map model props to media frame props. * - * @param {Object} modelProps - Model props. + * @param {Object} modelProps Model props. * @return {Object} Media frame props. */ mapModelToMediaFrameProps: function mapModelToMediaFrameProps( modelProps ) { diff --git a/src/js/_enqueues/wp/widgets/media.js b/src/js/_enqueues/wp/widgets/media.js index 66ec8e4306554..5d339308c5881 100644 --- a/src/js/_enqueues/wp/widgets/media.js +++ b/src/js/_enqueues/wp/widgets/media.js @@ -45,7 +45,7 @@ wp.mediaWidgets = ( function( $ ) { * @constructs wp.mediaWidgets.PersistentDisplaySettingsLibrary * @augments wp.media.controller.Library * - * @param {Object} options - Options. + * @param {Object} options Options. * * @return {void} */ @@ -57,7 +57,7 @@ wp.mediaWidgets = ( function( $ ) { /** * Sync changes to the current display settings back into the current customized. * - * @param {Backbone.Model} displaySettings - Modified display settings. + * @param {Backbone.Model} displaySettings Modified display settings. * @return {void} */ handleDisplaySettingChange: function handleDisplaySettingChange( displaySettings ) { @@ -72,7 +72,7 @@ wp.mediaWidgets = ( function( $ ) { * will sync back into the model storing the session's customized display * settings. * - * @param {Backbone.Model} model - Display settings model. + * @param {Backbone.Model} model Display settings model. * @return {Backbone.Model} Display settings model. */ display: function getDisplaySettingsModel( model ) { @@ -102,7 +102,7 @@ wp.mediaWidgets = ( function( $ ) { * * @since 4.9.0 * - * @param {Object} options - Options. + * @param {Object} options Options. * @return {void} */ initialize: function( options ) { @@ -137,7 +137,7 @@ wp.mediaWidgets = ( function( $ ) { /** * Set the disabled state on the Add to Widget button. * - * @param {boolean} disabled - Disabled. + * @param {boolean} disabled Disabled. * @return {void} */ setAddToWidgetButtonDisabled: function setAddToWidgetButtonDisabled( disabled ) { @@ -147,7 +147,7 @@ wp.mediaWidgets = ( function( $ ) { /** * Set or clear an error notice. * - * @param {string} notice - Notice. + * @param {string} notice Notice. * @return {void} */ setErrorNotice: function setErrorNotice( notice ) { @@ -358,7 +358,7 @@ wp.mediaWidgets = ( function( $ ) { * * Forked override of {wp.media.view.MediaFrame.Post#mainInsertToolbar()} to override text. * - * @param {wp.Backbone.View} view - Toolbar view. + * @param {wp.Backbone.View} view Toolbar view. * @this {wp.media.controller.Library} * @return {void} */ @@ -393,7 +393,7 @@ wp.mediaWidgets = ( function( $ ) { * * Forked override of {wp.media.view.MediaFrame.Post#mainEmbedToolbar()} to override text. * - * @param {wp.Backbone.View} toolbar - Toolbar view. + * @param {wp.Backbone.View} toolbar Toolbar view. * @this {wp.media.controller.Library} * @return {void} */ @@ -486,10 +486,10 @@ wp.mediaWidgets = ( function( $ ) { * @augments Backbone.View * @abstract * - * @param {Object} options - Options. - * @param {Backbone.Model} options.model - Model. - * @param {jQuery} options.el - Control field container element. - * @param {jQuery} options.syncContainer - Container element where fields are synced for the server. + * @param {Object} options Options. + * @param {Backbone.Model} options.model Model. + * @param {jQuery} options.el Control field container element. + * @param {jQuery} options.syncContainer Container element where fields are synced for the server. * * @return {void} */ @@ -721,7 +721,7 @@ wp.mediaWidgets = ( function( $ ) { /** * Handle click on link to Media Library to open modal, such as the link that appears when in the missing attachment error notice. * - * @param {jQuery.Event} event - Event. + * @param {jQuery.Event} event Event. * @return {void} */ handleMediaLibraryLinkClick: function handleMediaLibraryLinkClick( event ) { @@ -819,7 +819,7 @@ wp.mediaWidgets = ( function( $ ) { /** * Get the instance props from the media selection frame. * - * @param {wp.media.view.MediaFrame.Select} mediaFrame - Select frame. + * @param {wp.media.view.MediaFrame.Select} mediaFrame Select frame. * @return {Object} Props. */ getModelPropsFromMediaFrame: function getModelPropsFromMediaFrame( mediaFrame ) { @@ -868,7 +868,7 @@ wp.mediaWidgets = ( function( $ ) { /** * Map media frame props to model props. * - * @param {Object} mediaFrameProps - Media frame props. + * @param {Object} mediaFrameProps Media frame props. * @return {Object} Model props. */ mapMediaToModelProps: function mapMediaToModelProps( mediaFrameProps ) { @@ -919,7 +919,7 @@ wp.mediaWidgets = ( function( $ ) { /** * Map model props to media frame props. * - * @param {Object} modelProps - Model props. + * @param {Object} modelProps Model props. * @return {Object} Media frame props. */ mapModelToMediaFrameProps: function mapModelToMediaFrameProps( modelProps ) { @@ -1028,9 +1028,9 @@ wp.mediaWidgets = ( function( $ ) { * cast the attribute values from the hidden inputs' string values into * the appropriate data types (integers or booleans). * - * @param {string|Object} key - Attribute name or attribute pairs. - * @param {mixed|Object} [val] - Attribute value or options object. - * @param {Object} [options] - Options when attribute name and value are passed separately. + * @param {string|Object} key Attribute name or attribute pairs. + * @param {mixed|Object} [val] Attribute value or options object. + * @param {Object} [options] Options when attribute name and value are passed separately. * @return {wp.mediaWidgets.MediaWidgetModel} This model. */ set: function set( key, val, options ) { @@ -1119,8 +1119,8 @@ wp.mediaWidgets = ( function( $ ) { * * @memberOf wp.mediaWidgets * - * @param {jQuery.Event} event - Event. - * @param {jQuery} widgetContainer - Widget container element. + * @param {jQuery.Event} event Event. + * @param {jQuery} widgetContainer Widget container element. * * @return {void} */ @@ -1256,8 +1256,8 @@ wp.mediaWidgets = ( function( $ ) { * * @memberOf wp.mediaWidgets * - * @param {jQuery.Event} event - Event. - * @param {jQuery} widgetContainer - Widget container element. + * @param {jQuery.Event} event Event. + * @param {jQuery} widgetContainer Widget container element. * * @return {void} */ diff --git a/src/js/_enqueues/wp/widgets/text.js b/src/js/_enqueues/wp/widgets/text.js index df09ab40974ef..4b7af2e0d4a80 100644 --- a/src/js/_enqueues/wp/widgets/text.js +++ b/src/js/_enqueues/wp/widgets/text.js @@ -34,9 +34,9 @@ wp.textWidgets = ( function( $ ) { * @augments Backbone.View * @abstract * - * @param {Object} options - Options. - * @param {jQuery} options.el - Control field container element. - * @param {jQuery} options.syncContainer - Container element where fields are synced for the server. + * @param {Object} options Options. + * @param {jQuery} options.el Control field container element. + * @param {jQuery} options.syncContainer Container element where fields are synced for the server. * * @return {void} */ @@ -376,8 +376,8 @@ wp.textWidgets = ( function( $ ) { * * @memberOf wp.textWidgets * - * @param {jQuery.Event} event - Event. - * @param {jQuery} widgetContainer - Widget container element. + * @param {jQuery.Event} event Event. + * @param {jQuery} widgetContainer Widget container element. * * @return {void} */ @@ -484,8 +484,8 @@ wp.textWidgets = ( function( $ ) { * * @memberOf wp.textWidgets * - * @param {jQuery.Event} event - Event. - * @param {jQuery} widgetContainer - Widget container element. + * @param {jQuery.Event} event Event. + * @param {jQuery} widgetContainer Widget container element. * @return {void} */ component.handleWidgetUpdated = function handleWidgetUpdated( event, widgetContainer ) { diff --git a/src/js/media/controllers/state.js b/src/js/media/controllers/state.js index 12c07816251bc..1bacae9c0e734 100644 --- a/src/js/media/controllers/state.js +++ b/src/js/media/controllers/state.js @@ -6,11 +6,11 @@ * * A state has an event-driven lifecycle: * - * 'ready' triggers when a state is added to a state machine's collection. - * 'activate' triggers when a state is activated by a state machine. - * 'deactivate' triggers when a state is deactivated by a state machine. - * 'reset' is not triggered automatically. It should be invoked by the - * proper controller to reset the state to its default. + * 'ready' triggers when a state is added to a state machine's collection. + * 'activate' triggers when a state is activated by a state machine. + * 'deactivate' triggers when a state is deactivated by a state machine. + * 'reset' is not triggered automatically. It should be invoked by the + * proper controller to reset the state to its default. * * @memberOf wp.media.controller * @@ -85,7 +85,7 @@ var State = Backbone.Model.extend(/** @lends wp.media.controller.State.prototype * * @since 3.5.0 * @access private - */ + */ _preActivate: function() { this.active = true; }, diff --git a/src/js/media/models/attachment.js b/src/js/media/models/attachment.js index a116edf4add40..5c18eec27bf11 100644 --- a/src/js/media/models/attachment.js +++ b/src/js/media/models/attachment.js @@ -115,7 +115,7 @@ Attachment = Backbone.Model.extend(/** @lends wp.media.model.Attachment.prototyp /** * Saves attachment details using the `save-attachment-compat` action. * - * @param {Object} data The properties to be saved. + * @param {Object} data The properties to be saved. * @param {Object} options Sync options. e.g. patch, wait, success, error. * * @this Backbone.Model diff --git a/src/js/media/models/attachments.js b/src/js/media/models/attachments.js index fc6d79632d745..98d60e34726f5 100644 --- a/src/js/media/models/attachments.js +++ b/src/js/media/models/attachments.js @@ -18,8 +18,8 @@ * @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. + * @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 */{ diff --git a/src/js/media/models/post-media.js b/src/js/media/models/post-media.js index fd642a724f6e1..56d76bbd24d0e 100644 --- a/src/js/media/models/post-media.js +++ b/src/js/media/models/post-media.js @@ -2,7 +2,7 @@ * wp.media.model.PostMedia * * Shared model class for audio and video. Updates the model after - * "Add Audio|Video Source" and "Replace Audio|Video" states return + * "Add Audio|Video Source" and "Replace Audio|Video" states return * * @memberOf wp.media.model * diff --git a/src/js/media/models/query.js b/src/js/media/models/query.js index dbcdb87d77466..74559c8320b3e 100644 --- a/src/js/media/models/query.js +++ b/src/js/media/models/query.js @@ -7,7 +7,7 @@ var Attachments = wp.media.model.Attachments, * A collection of attachments that match the supplied query arguments. * * Note: Do NOT change this.args after the query has been initialized. - * Things will break. + * Things will break. * * @memberOf wp.media.model * diff --git a/src/js/media/views/attachments/browser.js b/src/js/media/views/attachments/browser.js index 3726d39e2f145..8d7d4dca51b76 100644 --- a/src/js/media/views/attachments/browser.js +++ b/src/js/media/views/attachments/browser.js @@ -187,8 +187,8 @@ AttachmentsBrowser = View.extend(/** @lends wp.media.view.AttachmentsBrowser.pro } /** - * @member {wp.media.view.Toolbar} - */ + * @member {wp.media.view.Toolbar} + */ this.toolbar = new wp.media.view.Toolbar( toolbarOptions ); this.views.add( this.toolbar ); diff --git a/src/js/media/views/focus-manager.js b/src/js/media/views/focus-manager.js index 36ef6a851b0da..749d283c7245d 100644 --- a/src/js/media/views/focus-manager.js +++ b/src/js/media/views/focus-manager.js @@ -31,14 +31,14 @@ var FocusManager = wp.media.View.extend(/** @lends wp.media.view.FocusManager.pr }, /** - * Determines which focus management mode to use. - * - * @since 5.3.0 - * - * @param {Object} event jQuery event object. - * - * @return {void} - */ + * Determines which focus management mode to use. + * + * @since 5.3.0 + * + * @param {Object} event jQuery event object. + * + * @return {void} + */ focusManagementMode: function( event ) { if ( this.mode === 'constrainTabbing' ) { this.constrainTabbing( event ); diff --git a/tools/gutenberg/copy.js b/tools/gutenberg/copy.js index 3da78e4b14611..367da7ba53127 100644 --- a/tools/gutenberg/copy.js +++ b/tools/gutenberg/copy.js @@ -34,10 +34,10 @@ const wpIncludesDir = path.join( rootDir, 'src', 'wp-includes' ); * * @typedef ScriptsConfig * @type {object} - * @property {string} source - Gutenberg-relative source directory (e.g. `'scripts'`). - * @property {string} destination - Subpath under `wp-includes/` where packages land (e.g. `'js/dist'`). - * @property {boolean} copyDirectories - Whether to copy whole directories (with optional renames) as-is. - * @property {Record} directoryRenames - Map of source directory name → destination directory name. + * @property {string} source Gutenberg-relative source directory (e.g. `'scripts'`). + * @property {string} destination Subpath under `wp-includes/` where packages land (e.g. `'js/dist'`). + * @property {boolean} copyDirectories Whether to copy whole directories (with optional renames) as-is. + * @property {Record} directoryRenames Map of source directory name → destination directory name. */ /** @@ -45,10 +45,10 @@ const wpIncludesDir = path.join( rootDir, 'src', 'wp-includes' ); * * @typedef BlockConfigSource * @type {object} - * @property {string} name - Human-readable label (e.g. `'block-library'`, `'widgets'`). - * @property {string} scripts - Gutenberg-relative path to the block scripts directory. - * @property {string} styles - Gutenberg-relative path to the block styles directory. - * @property {string} php - Gutenberg-relative path to the block PHP directory. + * @property {string} name Human-readable label (e.g. `'block-library'`, `'widgets'`). + * @property {string} scripts Gutenberg-relative path to the block scripts directory. + * @property {string} styles Gutenberg-relative path to the block styles directory. + * @property {string} php Gutenberg-relative path to the block PHP directory. */ /** @@ -56,8 +56,8 @@ const wpIncludesDir = path.join( rootDir, 'src', 'wp-includes' ); * * @typedef BlockConfig * @type {object} - * @property {string} destination - Subpath under `wp-includes/` where blocks land (e.g. `'blocks'`). - * @property {BlockConfigSource[]} sources - One entry per block family. + * @property {string} destination Subpath under `wp-includes/` where blocks land (e.g. `'blocks'`). + * @property {BlockConfigSource[]} sources One entry per block family. */ /** @@ -118,7 +118,7 @@ function readReturnedValueFromPHPFile( phpFilepath ) { /** * Check if a block is experimental by reading its block.json. * - * @param {string} blockJsonPath - Path to block.json file. + * @param {string} blockJsonPath Path to block.json file. * @return {boolean} True if block is experimental. */ function isExperimentalBlock( blockJsonPath ) { @@ -140,7 +140,7 @@ function isExperimentalBlock( blockJsonPath ) { * * Blocks marked as `"__experimental": true` in a `block.json` file are excluded. * - * @param {string} scriptsSrc - Path to the Gutenberg scripts source (e.g. `scripts/block-library`). + * @param {string} scriptsSrc Path to the Gutenberg scripts source (e.g. `scripts/block-library`). * @return {string[]} Stable block directory names. */ function getStableBlocks( scriptsSrc ) { @@ -159,7 +159,7 @@ function getStableBlocks( scriptsSrc ) { /** * Copy JavaScript files. * - * @param {ScriptsConfig} config - Scripts configuration from `COPY_CONFIG.scripts`. + * @param {ScriptsConfig} config Scripts configuration from `COPY_CONFIG.scripts`. */ function copyScripts( config ) { const scriptsSrc = path.join( gutenbergBuildDir, config.source ); @@ -248,7 +248,7 @@ function copyScripts( config ) { /** * Copy `block.json` files for every stable block. * - * @param {BlockConfig} config - Block configuration from `COPY_CONFIG.blocks`. + * @param {BlockConfig} config Block configuration from `COPY_CONFIG.blocks`. */ function copyBlockJson( config ) { const blocksDest = path.join( wpIncludesDir, config.destination ); @@ -283,7 +283,7 @@ function copyBlockJson( config ) { * Handles both the top-level `.php` dynamic block files and any nested * `*.php` helpers under `/` (e.g. `navigation-link/shared/render-submenu-icon.php`). * - * @param {BlockConfig} config - Block configuration from `COPY_CONFIG.blocks`. + * @param {BlockConfig} config Block configuration from `COPY_CONFIG.blocks`. */ function copyBlockPhp( config ) { const blocksDest = path.join( wpIncludesDir, config.destination ); @@ -338,7 +338,7 @@ function copyBlockPhp( config ) { /** * Copy per-block CSS files for every stable block. * - * @param {BlockConfig} config - Block configuration from `COPY_CONFIG.blocks`. + * @param {BlockConfig} config Block configuration from `COPY_CONFIG.blocks`. */ function copyBlockStyles( config ) { const blocksDest = path.join( wpIncludesDir, config.destination ); @@ -391,8 +391,8 @@ function generateScriptModulesPackages() { /** * Recursively process directory to find .asset.php files. * - * @param {string} dir - Directory to process. - * @param {string} baseDir - Base directory for relative paths. + * @param {string} dir Directory to process. + * @param {string} baseDir Base directory for relative paths. */ function processDirectory( dir, baseDir ) { if ( ! fs.existsSync( dir ) ) {