JSDoc: fix alignments, indentation, and unnecessary hyphen

.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,

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 ) {

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);

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();

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

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 ) {

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) {

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

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.

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

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: '',

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
  * <div class="accordion-container">
  *	<div class="accordion-section open">
  *		<h3 class="accordion-section-title"><button type="button" aria-expanded="true" aria-controls="target-1"></button></h3>
@@ -22,6 +24,7 @@
  *		</div>
  *	</div>
  * </div>
+ * ```
  *
  * Note that any appropriate tags may be used, as long as the above classes are present.
  *

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

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() {

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<string, Record<string, boolean>>} options - KSES options.
+	 * @param {import('htmlhint').HTMLParser}           parser   Parser.
+	 * @param {import('htmlhint').Reporter}             reporter Reporter.
+	 * @param {Record<string, Record<string, boolean>>} options  KSES options.
 	 * @return {void}
 	 */
 	init: function ( parser, reporter, options ) {