Add eslint-plugin-jsdoc for better JSDoc linting (#16869)

* feat(eslint-plugin): add eslint-plugin-jsdoc for improved jsdoc linting

* chore: fix all JSDoc eslint errors/warnings across the entire repository

packages/eslint-plugin/CHANGELOG.md

@@ -3,6 +3,7 @@
 ### Breaking Changes
 
 - The [`@wordpress/no-unused-vars-before-return` rule](https://github.com/WordPress/gutenberg/blob/master/packages/eslint-plugin/docs/rules/no-unused-vars-before-return.md) has been improved to exempt object destructuring only if destructuring to more than one property.
+- Stricter JSDoc linting using [`eslint-plugin-jsdoc`](https://github.com/gajus/eslint-plugin-jsdoc).
 
 ## 2.4.0 (2019-08-05)
 
@@ -19,6 +20,7 @@
 ### Improvements
 
 - The recommended `react` configuration specifies an option to [`@wordpress/no-unused-vars-before-return`](https://github.com/WordPress/gutenberg/blob/master/packages/eslint-plugin/docs/rules/no-unused-vars-before-return.md) to exempt React hooks usage, by convention of hooks beginning with "use" prefix.
+- The plugin now uses [`eslint-plugin-jsdoc`](https://github.com/gajus/eslint-plugin-jsdoc), rather than the `valid-jsdoc` rule, for more reliable linting of JSDoc blocks.
 
 ## 2.3.0 (2019-06-12)
 

packages/eslint-plugin/configs/es5.js

@@ -73,30 +73,6 @@ module.exports = {
 				'!': true,
 			},
 		} ],
-		'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,
-		} ],
 		'valid-typeof': 'error',
 		'vars-on-top': 'error',
 		'wrap-iife': 'error',

packages/eslint-plugin/configs/jsdoc.js

@@ -0,0 +1,29 @@
+const globals = require( 'globals' );
+
+module.exports = {
+	extends: [
+		'plugin:jsdoc/recommended',
+	],
+	settings: {
+		jsdoc: {
+			preferredTypes: {
+				object: 'Object',
+			},
+			tagNamePreference: {
+				returns: 'return',
+				yields: 'yield',
+			},
+		},
+	},
+	rules: {
+		'jsdoc/no-undefined-types': [ 'warning', {
+			// Required to reference browser types because we don't have the `browser` environment enabled for the project.
+			// Here we filter out all browser globals that don't begin with an uppercase letter because those
+			// generally refer to window-level event listeners and are not a valid type to reference (e.g. `onclick`).
+			definedTypes: Object.keys( globals.browser ).filter( ( k ) => /^[A-Z]/.test( k ) ),
+		} ],
+		'jsdoc/require-jsdoc': 'off',
+		'jsdoc/require-param-description': 'off',
+		'jsdoc/require-returns': 'off',
+	},
+};

packages/eslint-plugin/configs/recommended.js

@@ -5,6 +5,7 @@ module.exports = {
 		require.resolve( './custom.js' ),
 		require.resolve( './react.js' ),
 		require.resolve( './esnext.js' ),
+		require.resolve( './jsdoc.js' ),
 	],
 	env: {
 		node: true,

packages/eslint-plugin/package.json

@@ -25,9 +25,11 @@
 	"main": "index.js",
 	"dependencies": {
 		"babel-eslint": "^10.0.1",
+		"eslint-plugin-jsdoc": "^15.8.0",
 		"eslint-plugin-jsx-a11y": "^6.2.1",
 		"eslint-plugin-react": "^7.12.4",
 		"eslint-plugin-react-hooks": "^1.6.0",
+		"globals": "^12.0.0",
 		"requireindex": "^1.2.0"
 	},
 	"publishConfig": {