Update jsdoc eslint plugin (#72308)

* Update eslint-plugin-jsdoc peer dep

* fix jsdoc/require-returns-check rule

* Fix type in media modal component

* Fix jsdoc/check-param-names

* Fix more instances of jsdoc return issue by returning null from react components

Co-authored-by: Marin Atanasov <tyxla@abv.bg>

client/gutenberg/editor/controller.js

@@ -107,9 +107,9 @@ function waitForPreferredEditorView( context ) {
  * tracking), so we redirect the user to the WP Admin login page in order to store the auth cookie. Users will be
  * redirected back to Calypso when they are authenticated in WP Admin.
  *
- * @param {object} context  Shared context in the route.
- * @param {Function} next   Next registered callback for the route.
- * @returns {*}             Whatever the next callback returns.
+ * @param {object} context Shared context in the route.
+ * @param {Function} next  Next registered callback for the route.
+ * @returns {*}            Whatever the next callback returns.
  */
 export const authenticate = ( context, next ) => {
 	const state = context.store.getState();

client/lib/media/utils/generate-gallery-shortcode.js

@@ -11,7 +11,7 @@ import { stringify } from 'calypso/lib/shortcode';
  * optional set of parameters.
  *
  * @param  {object} settings Gallery settings
- * @returns {string}          Gallery shortcode
+ * @returns {string|undefined}          Gallery shortcode
  */
 export function generateGalleryShortcode( settings ) {
 	let attrs;

client/lib/media/utils/get-file-extension.js

@@ -11,7 +11,7 @@ import { isUri } from 'valid-url';
  * getFileExtension( new window.File( [''], 'example.gif' ) );
  * // All examples return 'gif'
  * @param  {(string|window.File|object)} media Media object or string
- * @returns {string}                     File extension
+ * @returns {string|undefined}                     File extension
  */
 export function getFileExtension( media ) {
 	let extension;

client/lib/media/utils/get-mime-prefix.js

@@ -9,7 +9,7 @@ import { getMimeType } from 'calypso/lib/media/utils/get-mime-type';
  * getMimeType( { mime_type: 'image/gif' } );
  * // All examples return 'image'
  * @param  {(string|window.File|object)} media Media object or mime type string
- * @returns {string}       The MIME type prefix
+ * @returns {string|undefined}       The MIME type prefix
  */
 export function getMimePrefix( media ) {
 	const mimeType = getMimeType( media );

client/lib/media/utils/get-mime-type.js

@@ -11,7 +11,7 @@ import { getFileExtension } from 'calypso/lib/media/utils/get-file-extension';
  * getMimeType( { mime_type: 'image/gif' } );
  * // All examples return 'image/gif'
  * @param  {(string|window.File|object)} media Media object or string
- * @returns {string}                     Mime type of the media, if known
+ * @returns {string|undefined}                     Mime type of the media, if known
  */
 export function getMimeType( media ) {
 	if ( ! media ) {

client/lib/media/utils/playtime.js

@@ -5,7 +5,7 @@
  * @example
  * playtime( 7 ); // -> "0:07"
  * @param  {number} duration Duration in seconds
- * @returns {string}          Human-readable duration
+ * @returns {string|undefined}          Human-readable duration
  */
 export function playtime( duration ) {
 	if ( isNaN( duration ) ) {

client/lib/media/utils/url.js

@@ -8,7 +8,7 @@ import resize from 'calypso/lib/resize-image-url';
  * @param  {object} media   Media object
  * @param  {object} options Optional options, accepting a `photon` boolean,
  *                          `maxWidth` pixel value, `resize` string, or `size`.
- * @returns {string}         URL to the media
+ * @returns {string|undefined} URL to the media
  */
 export function url( media, options ) {
 	if ( ! media ) {

client/lib/media/utils/validate-media-item.js

@@ -8,7 +8,7 @@ import { isSupportedFileTypeInPremium } from 'calypso/lib/media/utils/is-support
  *
  * @param  {object}      site Site object
  * @param  {object}      item Media item
- * @returns {Array|null}      Validation errors, or null if no site.
+ * @returns {Array|undefined} Validation errors, or undefined if no site.
  */
 export function validateMediaItem( site, item ) {
 	const itemErrors = [];

client/lib/notifications/note-block-parser.js

@@ -60,9 +60,11 @@ const encloses =
 	/**
 	 * Indicates if the given range encloses the first "inner" range
 	 *
-	 * @param {number} outerStart start of possibly-outer range
-	 * @param {number} outerEnd end of possibly-outer range
-	 * @returns {boolean} whether the "outer" range encloses the "inner" range
+	 * @param {object} range                      Range
+	 * @param {Array}  range.indices              Start and end of the range
+	 * @param {number} range.indices.0 innerStart Start index of the range
+	 * @param {number} range.indices.1 innerEnd   End index of the range
+	 * @returns {Function({indices: Number[]}): boolean} performs the check
 	 */
 	( { indices: [ outerStart, outerEnd ] = [ 0, 0 ] } ) =>
 		innerStart !== 0 && innerEnd !== 0 && outerStart <= innerStart && outerEnd >= innerEnd;

client/lib/payment-gateway-loader/index.js

@@ -6,7 +6,7 @@ const debug = debugFactory( 'calypso:payment-gateway' );
 /**
  * PaymentGatewayLoader component
  *
- * @returns { PaymentGatewayLoader } - an instance of PaymentGatewayLoader
+ * @returns {PaymentGatewayLoader|undefined} - an instance of PaymentGatewayLoader
  */
 function PaymentGatewayLoader() {
 	if ( ! ( this instanceof PaymentGatewayLoader ) ) {

client/lib/post-normalizer/rule-content-make-images-safe.js

@@ -31,7 +31,7 @@ const removeUnwantedAttributes = ( node ) => {
  */
 const imageShouldBeRemovedFromContent = ( imageUrl ) => {
 	if ( ! imageUrl ) {
-		return;
+		return false;
 	}
 
 	const bannedUrlParts = [

client/lib/redux-bridge/index.js

@@ -7,7 +7,7 @@ export function setReduxStore( store ) {
 /**
  * Dispatch an action against the current redux store
  *
- * @returns {any} Result of the dispatch
+ * @returns {undefined} Result of the dispatch
  */
 export function reduxDispatch( ...args ) {
 	if ( ! reduxStore ) {

client/lib/scroll-to/index.js

@@ -153,7 +153,7 @@ function circularOutEasing( val ) {
  * @param {Function} [options.onStart] - callback before start is called
  * @param {Function} [options.onComplete] - callback when scroll is finished
  * @param {HTMLElement} [options.container] - the container to scroll instead of window, if any
- * @returns {object} - the stepper
+ * @returns {object|undefined} - the stepper
  */
 export default function scrollTo( options ) {
 	const container = options.container || window;

client/my-sites/plans/legacy-plan-notice.jsx

@@ -8,7 +8,7 @@ import Notice from 'calypso/components/notice';
  * @param {boolean} eligibleForProPlan - Is the user eligible for pro plan?
  * @param {object} selectedSite - Site object from store.
  * @param {object} selectedSite.plan - The plan object nested inside the selectedSite object.
- * @returns - Legacy plan Notice component.
+ * @returns {import('react').Element} - Legacy plan Notice component.
  */
 const maybeRenderLegacyPlanNotice = ( eligibleForProPlan, { plan } ) => {
 	const eligibleLegacyPlan = isBlogger( plan ) || isPersonal( plan ) || isPremium( plan );
@@ -25,6 +25,7 @@ const maybeRenderLegacyPlanNotice = ( eligibleForProPlan, { plan } ) => {
 			></Notice>
 		);
 	}
+	return null;
 };
 
 export default maybeRenderLegacyPlanNotice;

client/post-editor/media-modal/detail/detail-preview-media-file.tsx

@@ -35,10 +35,14 @@ const EditorMediaModalDetailPreviewMediaFile: React.FC< Props & LocalizeProps >
 		);
 	}
 
+	const mediaUrl = url( item, {} );
+	if ( ! mediaUrl ) {
+		return null;
+	}
 	return (
 		<MediaFile
 			component={ component }
-			src={ url( item, {} ) }
+			src={ mediaUrl }
 			maxSize={ 20 * 1024 * 1024 }
 			onError={ () => setPreviewUnavailable( true ) }
 			controls

client/reader/lib/feed-display-helper/index.js

@@ -5,7 +5,7 @@ const exported = {
 	 * Remove the starting https, www. and trailing slash from a URL string
 	 *
 	 * @param {string} url URL to format
-	 * @returns {string} Formatted URL e.g. "https://www.wordpress.com/" --> "wordpress.com"
+	 * @returns {string|undefined} Formatted URL e.g. "https://www.wordpress.com/" --> "wordpress.com"
 	 */
 	formatUrlForDisplay: function ( url ) {
 		if ( ! url ) {

client/server/render/index.js

@@ -74,7 +74,7 @@ export function renderJsx( view, props ) {
  * @param {object} element - React element to be rendered to html
  * @param {string} key - cache key
  * @param {object} req - Request object
- * @returns {string} The rendered Layout
+ * @returns {string|undefined} The rendered Layout
  */
 function render( element, key, req ) {
 	try {

client/state/data-layer/wpcom-http/utils.js

@@ -10,23 +10,23 @@ const identity = ( data ) => data;
  * Returns response data from an HTTP request success action if available
  *
  * @param {object} action may contain HTTP response data
- * @returns {*|undefined} response data if available
+ * @returns {*} response data if available
  */
 export const getData = ( action ) => get( action, 'meta.dataLayer.data', undefined );
 
 /**
  * Returns error data from an HTTP request failure action if available
  *
  * @param {object} action may contain HTTP response error data
- * @returns {*|undefined} error data if available
+ * @returns {*} error data if available
  */
 export const getError = ( action ) => get( action, 'meta.dataLayer.error', undefined );
 
 /**
  * Returns (response) headers data from an HTTP request action if available
  *
  * @param   {object}      action Request action for which to retrieve HTTP response headers
- * @returns {*|undefined}        Headers data if available
+ * @returns {*} Headers data if available
  */
 export const getHeaders = ( action ) => get( action, 'meta.dataLayer.headers', undefined );
 
@@ -48,7 +48,7 @@ export const getProgress = ( action ) => get( action, 'meta.dataLayer.progress',
  * Returns stream record from an HTTP request action if available
  *
  * @param {object} action may contain stream record
- * @returns {*|undefined} response data if available
+ * @returns {*} response data if available
  */
 export const getStreamRecord = ( action ) =>
 	get( action, 'meta.dataLayer.streamRecord', undefined );

client/state/data-layer/wpcom/activity-log/rewind/restore-status/index.js

@@ -23,7 +23,7 @@ const ERROR_NOTICE_ID = 'AL_REW_RESTORESTATUS_ERR';
  * when it arrives. For now, it's statefully ugly.
  *
  * @param  {object} action Redux action
- * @returns {object}        Redux action
+ * @returns {object|undefined} Redux action
  */
 const fetchProgress = ( action ) => {
 	const { restoreId, siteId } = action;

client/state/data-layer/wpcom/read/streams/index.js

@@ -167,7 +167,7 @@ const streamApis = {
  * Request a page for the given stream
  *
  * @param  {object}   action   Action being handled
- * @returns {object} http action for data-layer to dispatch
+ * @returns {object|undefined} http action for data-layer to dispatch
  */
 export function requestPage( action ) {
 	const {

client/state/posts/utils/get-featured-image-id.js

@@ -6,7 +6,7 @@
  * in creating a post, the thumbnail ID is assigned to `featured_image`.
  *
  * @param  {object} post Post object
- * @returns {*} featured image id or undefined
+ * @returns {undefined|number|string} featured image id or undefined
  */
 export function getFeaturedImageId( post ) {
 	if ( ! post ) {

client/state/reader/lists/selectors.js

@@ -65,7 +65,7 @@ export const getSubscribedLists = createSelector(
  * @param  {object}  state  Global state tree
  * @param  {string}  owner  List owner
  * @param  {string}  slug  List slug
- * @returns {?object}        Reader list
+ * @returns {object|undefined} Reader list
  */
 export function getListByOwnerAndSlug( state, owner, slug ) {
 	if ( ! owner || ! slug ) {

package.json

@@ -240,7 +240,7 @@
 		"eslint-plugin-import": "^2.25.4",
 		"eslint-plugin-inclusive-language": "^2.2.0",
 		"eslint-plugin-jest": "^25.3.4",
-		"eslint-plugin-jsdoc": "^37.5.1",
+		"eslint-plugin-jsdoc": "^39.6.7",
 		"eslint-plugin-jsx-a11y": "^6.5.1",
 		"eslint-plugin-md": "^1.0.19",
 		"eslint-plugin-mocha": "^10.0.3",

packages/babel-plugin-i18n-calypso/src/index.js

@@ -80,7 +80,7 @@ const REGEXP_TRANSLATOR_COMMENT = /^\s*translators:\s*([\s\S]+)/im;
  * @param {object} path              Traversal path.
  * @param {number} _originalNodeLine Private: In recursion, line number of
  *                                     the original node passed.
- * @returns {?string} Extracted comment.
+ * @returns {string|undefined} Extracted comment.
  */
 function getExtractedComment( path, _originalNodeLine ) {
 	const { node, parent, parentPath } = path;

packages/calypso-build/webpack/util.js

@@ -3,8 +3,8 @@ const webpack = require( 'webpack' );
 /**
  * Transform webpack output.filename and output.chunkFilename to CSS variants
  *
- * @param {(string|undefined)} name filename, chunkFilename or undefined
- * @returns {(string|undefined)}     Transformed name or undefined
+ * @param {string|undefined} name filename, chunkFilename or undefined
+ * @returns {string|undefined}     Transformed name or undefined
  */
 function cssNameFromFilename( name ) {
 	if ( name ) {

packages/eslint-plugin-wpcalypso/package.json

@@ -27,7 +27,7 @@
 		"@babel/core": ">=7.17.5",
 		"eslint": ">=8.6.0",
 		"eslint-plugin-inclusive-language": "^2.2.0",
-		"eslint-plugin-jsdoc": "^37.5.1",
+		"eslint-plugin-jsdoc": "^39.6.7",
 		"eslint-plugin-react": "^7.28.0",
 		"eslint-plugin-react-hooks": "^4.3.0"
 	},

packages/i18n-calypso-cli/preprocess-xgettextjs-match.js

@@ -9,7 +9,7 @@
  *  - wraps quotes and backslashes for php consumption
  *
  * @param  {object} match - parser matching object
- * @returns {object} data object combining the strings and options passed into translate();
+ * @returns {object|undefined} data object combining the strings and options passed into translate();
  */
 module.exports = function preProcessXGettextJSMatch( match ) {
 	const finalProps = { line: match.line };

packages/i18n-calypso/src/i18n.js

@@ -357,7 +357,7 @@ I18N.prototype.hasTranslation = function () {
  * Exposes single translation method.
  * See sibling README
  *
- * @returns {string|object} translated text or an object containing React children that can be inserted into a parent component
+ * @returns {string|object|undefined} translated text or an object containing React children that can be inserted into a parent component
  */
 I18N.prototype.translate = function () {
 	const options = normalizeTranslateArguments( arguments );

packages/social-previews/src/twitter-preview/tweet.jsx

@@ -94,7 +94,7 @@ export class Tweet extends PureComponent {
 	 */
 	renderMedia( media ) {
 		if ( ! media ) {
-			return;
+			return null;
 		}
 
 		// Ensure we're only trying to show valid media, and the correct quantity.
@@ -133,7 +133,7 @@ export class Tweet extends PureComponent {
 		] );
 
 		if ( 0 === filteredMedia.length ) {
-			return;
+			return null;
 		}
 
 		return (
@@ -168,7 +168,7 @@ export class Tweet extends PureComponent {
 	 */
 	renderQuoteTweet( tweet ) {
 		if ( ! tweet ) {
-			return;
+			return null;
 		}
 
 		return (
@@ -192,7 +192,7 @@ export class Tweet extends PureComponent {
 	 */
 	renderCard( card ) {
 		if ( ! card ) {
-			return;
+			return null;
 		}
 
 		const { description, image, title, type, url } = card;

packages/wpcom.js/src/index.js

@@ -26,7 +26,7 @@ const DEFAULT_ASYNC_TIMEOUT = 30000;
  *
  * @param {string} [token] - OAuth API access token
  * @param {Function} [reqHandler] - function Request Handler
- * @returns {WPCOM} wpcom instance
+ * @returns {WPCOM|undefined} wpcom instance
  */
 export default function WPCOM( token, reqHandler ) {
 	if ( ! ( this instanceof WPCOM ) ) {

packages/wpcom.js/src/lib/me.js

@@ -8,7 +8,7 @@ import MeTwoStep from './me.two-step';
  * Create `Me` instance
  *
  * @param {object} wpcom - wpcom instance
- * @returns {null} null
+ * @returns {undefined|Me} New Me instance or undefined.
  */
 export default function Me( wpcom ) {
 	if ( ! ( this instanceof Me ) ) {

packages/wpcom.js/src/lib/me.settings.js

@@ -7,7 +7,7 @@ import MeProfileLinks from './me.settings.profile-links';
  * Use a `WPCOM#Me` instance to create a new `MeSettings` instance.
  *
  * @param {WPCOM} wpcom - wpcom instance
- * @returns {null} null
+ * @returns {MeSettings|undefined}
  */
 export default function MeSettings( wpcom ) {
 	if ( ! ( this instanceof MeSettings ) ) {

packages/wpcom.js/src/lib/me.settings.profile-links.js

@@ -7,7 +7,7 @@ const root = '/me/settings/profile-links';
  * `ProfileLinks` constructor.
  *
  * @param {WPCOM} wpcom - wpcom instance
- * @returns {null} null
+ * @returns {ProfileLinks|undefined}
  */
 export default function ProfileLinks( wpcom ) {
 	if ( ! ( this instanceof ProfileLinks ) ) {

packages/wpcom.js/src/lib/site.category.js

@@ -4,7 +4,7 @@
  * @param {string} [slug] - category slug
  * @param {string} sid - site id
  * @param {WPCOM} wpcom - wpcom instance
- * @returns {null} null
+ * @returns {Category|undefined}
  */
 export default function Category( slug, sid, wpcom ) {
 	if ( ! sid ) {

packages/wpcom.js/src/lib/site.comment.js

@@ -7,7 +7,7 @@ import commentLike from './site.comment.like';
  * @param {string} [pid] post id
  * @param {string} sid site id
  * @param {WPCOM} wpcom - wpcom instance
- * @returns {null} null
+ * @returns {Comment|undefined}
  */
 export default function Comment( cid, pid, sid, wpcom ) {
 	if ( ! sid ) {