Build/Test Tools: Enable JSDocs to be linted with ESLint.

As part of the [Javascript Inline Docs Initiative](https://make.wordpress.org/core/handbook/docs/inline/js/) this add some tooling to lint Javascript docblocks. Two new commands:

* `npm run lint:jsdoc`
* `npm run lint:jsdoc:fix`

The latter will run the linter and try to fix an possible issues automatically.

Fixes #43828.
Props netweb, atimmer, kamataryo, whyisjake.



git-svn-id: https://develop.svn.wordpress.org/trunk@48650 602fd350-edb4-49c9-b593-d223f7449a82

Author: whyisjake

.eslintignore

@@ -0,0 +1,15 @@
+# Files and folders related to build/test tools
+/build
+/node_modules
+/tests
+/vendor
+/tools
+
+# Excluded files and folders based on `jsdoc.conf.json` exclusions
+/src/js/_enqueues/vendor
+
+# Webpack built files
+/src/wp-includes/js/media-*
+
+# Themes
+src/wp-content/themes/

.eslintrc-jsdoc.js

@@ -0,0 +1,29 @@
+module.exports = {
+	rules: {
+		'require-jsdoc': 'off',
+		'valid-jsdoc': [ 'error', {
+			prefer: {
+				arg: 'param',
+				argument: 'param',
+				extends: 'augments',
+				returns: 'return',
+			},
+			preferType: {
+				array: 'Array',
+				bool: 'boolean',
+				Boolean: 'boolean',
+				float: 'number',
+				Float: 'number',
+				int: 'number',
+				integer: 'number',
+				Integer: 'number',
+				Number: 'number',
+				object: 'Object',
+				String: 'string',
+				Void: 'void',
+			},
+			requireParamDescription: false,
+			requireReturn: false,
+		} ],
+	},
+};

package.json

@@ -155,6 +155,8 @@
 		"test": "grunt test",
 		"watch": "grunt watch",
 		"grunt": "grunt",
+		"lint:jsdoc": "wp-scripts lint-js",
+		"lint:jsdoc:fix": "wp-scripts lint-js --fix",
 		"env:start": "node ./tools/local-env/scripts/start.js",
 		"env:stop": "node ./tools/local-env/scripts/docker.js down",
 		"env:restart": "npm run env:stop && npm run env:start",

src/js/_enqueues/admin/common.js

@@ -137,7 +137,7 @@ window.columns = {
 	 *
 	 * @since 3.1.0
 	 *
-	 * @param {int} diff The modifier for the column span.
+	 * @param {number} diff The modifier for the column span.
 	 */
 	colSpanChange : function(diff) {
 		var $t = $('table').find('.colspanchange'), n;
@@ -384,7 +384,7 @@ $permalinkStructure.on( 'focus', function( event ) {
  * If the structure is already used in the custom permalink structure,
  * it will be disabled.
  *
- * @param {object} button Button jQuery object.
+ * @param {Object} button Button jQuery object.
  */
 function changeStructureTagButtonState( button ) {
 	if ( -1 !== $permalinkStructure.val().indexOf( button.text().trim() ) ) {

src/js/_enqueues/admin/edit-comments.js

@@ -159,7 +159,7 @@ var getCount, updateCount, updateCountText, updatePending, updateApproved,
 	 *
 	 * @since 5.2.0
 	 *
-	 * @param {object} response Ajax response from the server that includes a
+	 * @param {Object} response Ajax response from the server that includes a
 	 *                          translated "comments in moderation" message.
 	 *
 	 * @return {void}

src/js/_enqueues/admin/inline-edit-post.js

@@ -389,7 +389,7 @@ window.wp = window.wp || {};
 	 *
 	 * @since 2.7.0
 	 *
-	 * @param {int} id The ID for the post that has been changed.
+	 * @param {number} id The ID for the post that has been changed.
 	 * @return {boolean} False, so the form does not submit when pressing
 	 *                   Enter on a focused field.
 	 */

src/js/_enqueues/admin/post.js

@@ -34,8 +34,8 @@ window.wp = window.wp || {};
 		 *
 		 * @memberof commentsBox
 		 *
-		 * @param {int} total Total number of comments for this post.
-		 * @param {int} num   Optional. Number of comments to fetch, defaults to 20.
+		 * @param {number} total Total number of comments for this post.
+		 * @param {number} num   Optional. Number of comments to fetch, defaults to 20.
 		 * @return {boolean} Always returns false.
 		 */
 		get : function(total, num) {
@@ -94,7 +94,7 @@ window.wp = window.wp || {};
 		 *
 		 * @memberof commentsBox
 		 *
-		 * @param {int} total Total number of comments to load.
+		 * @param {number} total Total number of comments to load.
 		 */
 		load: function(total){
 			this.st = jQuery('#the-comment-list tr.comment:visible').length;
@@ -116,7 +116,7 @@ window.wp = window.wp || {};
 	/**
 	 * Set the Image ID of the Featured Image
 	 *
-	 * @param {int} id The post_id of the image to use as Featured Image.
+	 * @param {number} id The post_id of the image to use as Featured Image.
 	 *
 	 * @global
 	 */

src/js/_enqueues/admin/postbox.js

@@ -154,8 +154,8 @@
 		 * @since 5.5.0
 		 *
 		 * @param {string} position The "previous" or "next" sortables area.
-		 * @param {object} button   The jQuery object representing the button that was clicked.
-		 * @param {object} postbox  The jQuery object representing the postbox to be moved.
+		 * @param {Object} button   The jQuery object representing the button that was clicked.
+		 * @param {Object} postbox  The jQuery object representing the postbox to be moved.
 		 *
 		 * @return {void}
 		 */

src/js/_enqueues/admin/tags-suggest.js

@@ -30,8 +30,8 @@
 	 *
 	 * @since 4.7.0
 	 *
-	 * @param {object} options Options that are passed to UI Autocomplete. Can be used to override the default settings.
-	 * @return {object} jQuery instance.
+	 * @param {Object} options Options that are passed to UI Autocomplete. Can be used to override the default settings.
+	 * @return {Object} jQuery instance.
 	 */
 	$.fn.wpTagsSuggest = function( options ) {
 		var cache;

src/js/_enqueues/admin/widgets.js

@@ -234,7 +234,7 @@ window.wpWidgets = {
 			 *
 			 * @ignore
 			 *
-			 * @param {object} event jQuery event object.
+			 * @param {Object} event jQuery event object.
 			 */
 			over: function( event ) {
 				var $wrap = $( event.target ).parent();
@@ -259,7 +259,7 @@ window.wpWidgets = {
 			 *
 			 * @ignore
 			 *
-			 * @param {object} event jQuery event object.
+			 * @param {Object} event jQuery event object.
 			 */
 			out: function( event ) {
 				if ( wpWidgets.hoveredSidebar ) {
@@ -729,7 +729,7 @@ window.wpWidgets = {
 	 *
 	 * Used when a Widget gets dragged in/out of the Sidebar and never dropped.
 	 *
-	 * @param {object} event jQuery event object.
+	 * @param {Object} event jQuery event object.
 	 */
 	closeSidebar: function( event ) {
 		this.hoveredSidebar

src/js/_enqueues/lib/admin-bar.js

@@ -294,8 +294,8 @@
 	 * @since 5.3.1
 	 *
 	 * @param {HTMLElement} element The HTML element.
-	 * @param {String}      className The class name.
-	 * @return {bool} Whether the element has the className.
+	 * @param {string}      className The class name.
+	 * @return {boolean} Whether the element has the className.
 	 */
 	function hasClass( element, className ) {
 		var classNames;
@@ -320,7 +320,7 @@
 	 * @since 5.3.1
 	 *
 	 * @param {HTMLElement} element The HTML element.
-	 * @param {String}      className The class name.
+	 * @param {string}      className The class name.
 	 */
 	function addClass( element, className ) {
 		if ( ! element ) {
@@ -344,7 +344,7 @@
 	 * @since 5.3.1
 	 *
 	 * @param {HTMLElement} element The HTML element.
-	 * @param {String}      className The class name.
+	 * @param {string}      className The class name.
 	 */
 	function removeClass( element, className ) {
 		var testName,

src/js/_enqueues/lib/comment-reply.js

@@ -265,9 +265,9 @@ window.addComment = ( function( window ) {
 	 * @since 5.1.0
 	 *
 	 * @param {HTMLElement} Element DOM element with the attribute.
-	 * @param {String}      Attribute the attribute to get.
+	 * @param {string}      Attribute the attribute to get.
 	 *
-	 * @return {String}
+	 * @return {string}
 	 */
 	function getDataAttribute( element, attribute ) {
 		if ( supportsDataset ) {
@@ -298,11 +298,11 @@ window.addComment = ( function( window ) {
 	 *
 	 * @memberOf addComment
 	 *
-	 * @param {String} addBelowId HTML ID of element the form follows.
-	 * @param {String} commentId  Database ID of comment being replied to.
-	 * @param {String} respondId  HTML ID of 'respond' element.
-	 * @param {String} postId     Database ID of the post.
-	 * @param {String} replyTo    Form heading content.
+	 * @param {string} addBelowId HTML ID of element the form follows.
+	 * @param {string} commentId  Database ID of comment being replied to.
+	 * @param {string} respondId  HTML ID of 'respond' element.
+	 * @param {string} postId     Database ID of the post.
+	 * @param {string} replyTo    Form heading content.
 	 */
 	function moveForm( addBelowId, commentId, respondId, postId, replyTo ) {
 		// Get elements based on their IDs.

src/js/_enqueues/lib/image-edit.js

@@ -73,7 +73,7 @@
 	 * @memberof imageEdit
 	 *
 	 * @param {jQuery}         el The element that should be modified.
-	 * @param {bool|number}    s  The state for the element. If set to true
+	 * @param {boolean|number}    s  The state for the element. If set to true
 	 *                            the element is disabled,
 	 *                            otherwise the element is enabled.
 	 *                            The function is sometimes called with a 0 or 1
@@ -577,7 +577,7 @@
 	 *
 	 * @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 {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.
@@ -774,10 +774,10 @@
 			 *
 			 * @ignore
 			 *
-			 * @param {object} img jQuery object representing the image.
-			 * @param {object} c   The selection.
+			 * @param {Object} img jQuery object representing the image.
+			 * @param {Object} c   The selection.
 			 *
-			 * @return {object}
+			 * @return {Object}
 			 */
 			onSelectEnd: function(img, c) {
 				imageEdit.setCropSelection(postid, c);
@@ -788,8 +788,8 @@
 			 *
 			 * @ignore
 			 *
-			 * @param {object} img jQuery object representing the image.
-			 * @param {object} c   The selection.
+			 * @param {Object} img jQuery object representing the image.
+			 * @param {Object} c   The selection.
 			 *
 			 * @return {void}
 			 */
@@ -809,7 +809,7 @@
 	 * @memberof imageEdit
 	 *
 	 * @param {number} postid The post ID.
-	 * @param {object} c      The selection.
+	 * @param {Object} c      The selection.
 	 *
 	 * @return {boolean}
 	 */
@@ -841,9 +841,9 @@
 	 * @memberof imageEdit
 	 *
 	 * @param {number}  postid The post ID.
-	 * @param {bool}    warn   Warning message.
+	 * @param {boolean}    warn   Warning message.
 	 *
-	 * @return {void|bool} Returns false if there is a warning.
+	 * @return {void|boolean} Returns false if there is a warning.
 	 */
 	close : function(postid, warn) {
 		warn = warn || false;
@@ -908,7 +908,7 @@
 	 *
 	 * @memberof imageEdit
 	 *
-	 * @param {object} op     The original position.
+	 * @param {Object} op     The original position.
 	 * @param {number} postid The post ID.
 	 * @param {string} nonce  The nonce.
 	 *
@@ -945,7 +945,7 @@
 	 * @param {string} angle  The angle the image is rotated with.
 	 * @param {number} postid The post ID.
 	 * @param {string} nonce  The nonce.
-	 * @param {object} t      The target element.
+	 * @param {Object} t      The target element.
 	 *
 	 * @return {boolean}
 	 */
@@ -967,7 +967,7 @@
 	 * @param {number} axis   The axle the image is flipped on.
 	 * @param {number} postid The post ID.
 	 * @param {string} nonce  The nonce.
-	 * @param {object} t      The target element.
+	 * @param {Object} t      The target element.
 	 *
 	 * @return {boolean}
 	 */
@@ -988,7 +988,7 @@
 	 *
 	 * @param {number} postid The post ID.
 	 * @param {string} nonce  The nonce.
-	 * @param {object} t      The target object.
+	 * @param {Object} t      The target object.
 	 *
 	 * @return {void|boolean} Returns false if the crop button is disabled.
 	 */

src/js/_enqueues/lib/lists.js

@@ -202,7 +202,7 @@ wpList = {
 	 * 6. 0 if none can be found.
 	 *
 	 * @param {jQuery} element  Element that triggered the request.
-	 * @param {object} settings Settings for the Ajax request.
+	 * @param {Object} settings Settings for the Ajax request.
 	 * @return {string|number} Nonce
 	 */
 	nonce: function( element, settings ) {
@@ -258,9 +258,9 @@ wpList = {
 	 * Calls a confirm callback to verify the action that is about to be performed.
 	 *
 	 * @param {HTMLElement} list     The DOM element.
-	 * @param {object}      settings Settings for this list.
+	 * @param {Object}      settings Settings for this list.
 	 * @param {string}      action   The type of action to perform: 'add', 'delete', or 'dim'.
-	 * @return {object|boolean} Settings if confirmed, false if not.
+	 * @return {Object|boolean} Settings if confirmed, false if not.
 	 */
 	pre: function( list, settings, action ) {
 		var $element, backgroundColor, confirmed;
@@ -297,7 +297,7 @@ wpList = {
 	 * Adds an item to the list via Ajax.
 	 *
 	 * @param {HTMLElement} element  The DOM element.
-	 * @param {object}      settings Settings for this list.
+	 * @param {Object}      settings Settings for this list.
 	 * @return {boolean} Whether the item was added.
 	 */
 	ajaxAdd: function( element, settings ) {
@@ -399,7 +399,7 @@ wpList = {
 	 * Delete an item in the list via Ajax.
 	 *
 	 * @param {HTMLElement} element  A DOM element containing item data.
-	 * @param {object}      settings Settings for this list.
+	 * @param {Object}      settings Settings for this list.
 	 * @return {boolean} Whether the item was deleted.
 	 */
 	ajaxDel: function( element, settings ) {
@@ -486,7 +486,7 @@ wpList = {
 	 * Dim an item in the list via Ajax.
 	 *
 	 * @param {HTMLElement} element  A DOM element containing item data.
-	 * @param {object}      settings Settings for this list.
+	 * @param {Object}      settings Settings for this list.
 	 * @return {boolean} Whether the item was dim'ed.
 	 */
 	ajaxDim: function( element, settings ) {
@@ -621,7 +621,7 @@ wpList = {
 	 * Adds something.
 	 *
 	 * @param {HTMLElement} element  A DOM element containing item data.
-	 * @param {object}      settings Settings for this list.
+	 * @param {Object}      settings Settings for this list.
 	 * @return {boolean} Whether the item was added.
 	 */
 	add: function( element, settings ) {