jetpack-mu-wpcom: remove linting rule overrides (#40578)

* Fix JSDoc lints

* Remove unneeded overrides

* Add changelog

projects/packages/jetpack-mu-wpcom/bin/sync-newspack-blocks-formatter.js

@@ -32,8 +32,9 @@ module.exports = function transformer( file, api ) {
 /**
  * Whether the node is a function call with the specific name
  *
- * @param node         - The AST node
- * @param functionName - The function name we want to check
+ * @param {object} node         - The AST node
+ * @param {string} functionName - The function name we want to check
+ * @return {boolean}            - True if the node is a function call with the specified name, false otherwise.
  */
 function isFunctionCallWithName( node, functionName ) {
 	return (

projects/packages/jetpack-mu-wpcom/changelog/fix-jetpack-mu-wpcom-eslint_fixes

@@ -0,0 +1,4 @@
+Significance: patch
+Type: fixed
+
+Code: Clean up JSDoc comments.

projects/packages/jetpack-mu-wpcom/eslint.config.mjs

@@ -7,9 +7,6 @@ export default [
 		rules: {
 			'testing-library/prefer-screen-queries': 'off',
 			'react/jsx-no-bind': 'off',
-			// @todo Turn these back on for JS here. The block below handles TS.
-			'jsdoc/require-returns': 'off',
-			'jsdoc/require-param-type': 'off',
 		},
 	},
 	{

projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/keyboard-navigation.tsx

@@ -28,6 +28,7 @@ const KeyboardNavigation: React.FunctionComponent< Props > = ( {
 } ) => {
 	/**
 	 * Expand Tour Nav
+	 * @return {null} This component is non-rendering.
 	 */
 	function ExpandedTourNav() {
 		useKeydownHandler( {
@@ -43,8 +44,9 @@ const KeyboardNavigation: React.FunctionComponent< Props > = ( {
 
 	/**
 	 * Minimize Tour Nav
+	 * @return {null} This component is non-rendering.
 	 */
-	function MinimizedTourNav() {
+	function MinimizedTourNav(): null {
 		useKeydownHandler( { onEscape: onDismiss( 'esc-key-minimized' ), tourContainerRef } );
 
 		return null;

projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-focus-handler.ts

@@ -5,7 +5,8 @@ import { useEffect, useCallback, useState } from '@wordpress/element';
 
 /**
  * A hook that returns true/false if ref node receives focus by either tabbing or clicking into any of its children.
- * @param ref - React.MutableRefObject< null | HTMLElement >
+ * @param  ref - React.MutableRefObject< null | HTMLElement >
+ * @return {boolean} - True if the ref node has focus, false otherwise.
  */
 const useFocusHandler = ( ref: React.MutableRefObject< null | HTMLElement > ): boolean => {
 	const [ hasFocus, setHasFocus ] = useState( false );

projects/packages/jetpack-mu-wpcom/src/features/block-inserter-modifications/src/contextual-tip.js

@@ -11,6 +11,7 @@ import tipsList from './list';
  * @param {string}   props.searchTerm    - Search term text.
  * @param {boolean}  props.random        - Whether to choose a random tooltip on multiple matches.
  * @param {Function} props.canUserCreate - Function to check user permission.
+ * @return {JSX.Element|null} - The contextual tip element or null if no tip is found.
  */
 function ContextualTip( { searchTerm, random = false, canUserCreate } ) {
 	if ( ! searchTerm ) {

projects/packages/jetpack-mu-wpcom/src/features/block-inserter-modifications/src/list.js

@@ -5,9 +5,10 @@ import TipLink from './tip-link';
 /**
  * Creates the tip content as an React element or text.
  *
- * @param text         - The tip description text string.
- * @param conversion   - The map used to convert the string to an element.
- * @param textFallback - The fallback text for the tip description.
+ * @param {string}                  text         - The tip description text string.
+ * @param {Record<string, Element>} conversion   - The map used to convert the string to an element.
+ * @param {string}                  textFallback - The fallback text for the tip description.
+ * @return {JSX.Element|string} The tip content as a React element or the fallback text.
  */
 function getTipDescription( text, conversion, textFallback ) {
 	if ( typeof createInterpolateElement !== 'undefined' ) {

projects/packages/jetpack-mu-wpcom/src/features/block-inserter-modifications/src/tip-link.js

@@ -8,6 +8,7 @@ const isEditorIFramed = inIframe();
  * @param {object} props          - The function props.
  * @param {string} props.children - The tip content.
  * @param {string} props.section  - The tip context section.
+ * @return {JSX.Element} The link element.
  */
 export default function ( { children, section } ) {
 	const { hostname } = window.location;

projects/packages/jetpack-mu-wpcom/src/features/block-theme-previews/modal.jsx

@@ -8,6 +8,8 @@ import './modal.scss';
 
 /**
  * The modal that shows in the Site Editor the first time a user previews a block theme.
+ *
+ * @return {JSX.Element|null} The modal component if visible and in the Site Editor, otherwise null.
  */
 export default function BlockThemePreviewsModal() {
 	const stylesheet = getPreviewedThemeStylesheet();

projects/packages/jetpack-mu-wpcom/src/features/block-theme-previews/utils.js

@@ -2,6 +2,8 @@ import { getQueryArg } from '@wordpress/url';
 
 /**
  * Returns the theme stylesheet of the currently previewed theme.
+ *
+ * @return {string} The query arg.
  */
 export function getPreviewedThemeStylesheet() {
 	return getQueryArg( window.location.href, 'wp_theme_preview' );

projects/packages/jetpack-mu-wpcom/src/features/jetpack-global-styles/customizer-fonts/index.js

@@ -1,6 +1,6 @@
 /**
  * Record a Tracks event.
- * @param tracksEventName - {string} The name of the event to record in Tracks.
+ * @param {string} tracksEventName - The name of the event to record in Tracks.
  */
 function recordTracksEvent( tracksEventName ) {
 	window.parent.window._tkq = window.parent.window._tkq || [];

projects/packages/jetpack-mu-wpcom/src/features/newspack-blocks/blog-posts/editor.js

@@ -13,7 +13,8 @@ const blockName = 'a8c/blog-posts';
 /**
  * Set the name of the block transformation
  *
- * @param name - The name of the block
+ * @param {string} name - The name of the block
+ * @return {string} The potentially-transformed block name
  */
 function setBlockTransformationName( name ) {
 	return name !== 'newspack-blocks/homepage-articles' ? name : blockName;

projects/packages/jetpack-mu-wpcom/src/features/newspack-blocks/carousel/editor.js

@@ -6,7 +6,8 @@ import { settings } from '../synced-newspack-blocks/blocks/carousel';
 /**
  * Set the name of the block transformation
  *
- * @param name - The name of the block
+ * @param {string} name - The name of the block
+ * @return {string} The potentially-transformed block name
  */
 function setBlockTransformationName( name ) {
 	return name !== 'newspack-blocks/carousel' ? name : CAROUSEL_BLOCK_NAME;

projects/packages/jetpack-mu-wpcom/src/features/starter-page-templates/page-patterns-plugin.tsx

@@ -45,9 +45,10 @@ function findPostContentBlock( blocks: BlockInstance[] ): BlockInstance | null {
 /**
  * Starter page templates feature plugin
  *
- * @param props - An object that receives the page patterns
+ * @param  props - An object that receives the page patterns
+ * @return {JSX.Element} The rendered page pattern modal component.
  */
-export function PagePatternsPlugin( props: PagePatternsPluginProps ) {
+export function PagePatternsPlugin( props: PagePatternsPluginProps ): JSX.Element {
 	const { setOpenState } = useDispatch( pageLayoutStore );
 	const { setUsedPageOrPatternsModal } = useDispatch( 'automattic/wpcom-welcome-guide' );
 	const { replaceInnerBlocks } = useDispatch( 'core/block-editor' );

projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/src/components/FrequencyToggle/index.tsx

@@ -23,14 +23,15 @@ type Option = {
  * @param {Function}             props.onChange       - callback when the selected option changes
  * @param {Option[]}             props.selectedOption - the currently selected option
  * @param {boolean}              props.disabled       - whether the toggle is disabled
+ * @return {JSX.Element} The rendered component.
  */
 export function FrequencyToggle( {
 	name = 'frequency-toggle',
 	initialOptions,
 	onChange,
 	selectedOption,
 	disabled,
-}: FrequencyToggleProps ) {
+}: FrequencyToggleProps ): JSX.Element {
 	return (
 		<div className="verbum-frequency-toggle">
 			<fieldset className="fieldset" disabled={ disabled }>

projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/src/components/logged-in.tsx

@@ -10,10 +10,11 @@ import { NewPostsNotifications } from './new-posts-notifications';
 
 /**
  * Replace the first occurrence of %s in a string with a parameter.
- * @param s     - string to replace
- * @param param - parameter to replace with
+ * @param {string} s     - string to replace
+ * @param {string} param - parameter to replace with
+ * @return {string} The string with the first occurrence of %s replaced by the parameter.
  */
-function sprintf( s: string, param: string ) {
+function sprintf( s: string, param: string ): string {
 	return s.replace( '%s', param );
 }
 

projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/src/hooks/useSubscriptionApi.tsx

@@ -21,8 +21,10 @@ const getSubscriptionDetails = async () => {
 
 /**
  * Hook to handle subscription API calls.
+ *
+ * @return {object} Object containing functions to manage subscriptions.
  */
-export default function useSubscriptionApi() {
+export default function useSubscriptionApi(): object {
 	const { siteId } = VerbumComments;
 	const [ subscriptionSettingsIsLoading, setSubscriptionSettingsIsLoading ] = useState( true );
 

projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/src/i18n.ts

@@ -6,8 +6,9 @@ declare global {
 
 /**
  * Translates a string.
- * @param string - The string to translate.
+ * @param {string} string - The string to translate.
+ * @return {string} The translated string, or original string if no translation is found.
  */
-export function translate( string: string ) {
+export function translate( string: string ): string {
 	return window.VerbumComments?.[ string ] ?? string;
 }

projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/src/utils.ts

@@ -41,8 +41,10 @@ export const canWeAccessCookies = () => {
 
 /**
  * Uses the current bundle's size and the time it took to download and execute to estimate connection speed.
+ *
+ * @return {boolean} - True if the connection is fast, false otherwise.
  */
-export function isFastConnection() {
+export function isFastConnection(): boolean {
 	// Hardcoding the size of the bundle.
 	const bytes = 30000;
 	const bytesPerMs = bytes / VerbumComments.fullyLoadedTime;

projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/tests/utils.ts

@@ -1,13 +1,15 @@
 /**
  * Create a random email
+ * @return {string} A random email
  */
-export function createRandomEmail() {
+export function createRandomEmail(): string {
 	return `${ Math.random().toString( 36 ).substring( 7 ) }@example.com`;
 }
 /**
  * Create a random name
+ * @return {string} A random name
  */
-export function createRandomName() {
+export function createRandomName(): string {
 	return ` ${ Math.random().toString( 36 ).substring( 7 ) } ${ Math.random()
 		.toString( 36 )
 		.substring( 7 ) }`;
@@ -66,8 +68,9 @@ const commonWords = [
 
 /**
  * Create a random comment
+ * @return {string} A random comment
  */
-export function createRandomComment() {
+export function createRandomComment(): string {
 	const sentence = [];
 	for ( let i = 0; i < 15; i++ ) {
 		sentence.push( commonWords[ Math.floor( Math.random() * commonWords.length ) ] );

projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-description-links/src/inline-support-link.tsx

@@ -21,6 +21,7 @@ interface Props {
  * @param {string}                                                     props.title    - Block title.
  * @param {string}                                                     props.url      - Support link URL.
  * @param {number}                                                     props.postId   - Post ID.
+ * @return {React.JSX.Element} The component to render.
  */
 export default function DescriptionSupportLink( {
 	children,

projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/block-editor-nux.js

@@ -24,6 +24,7 @@ import LaunchWpcomWelcomeTour from './welcome-tour/tour-launch';
 
 /**
  * The WelcomeTour component
+ * @return {JSX.Element|null} The WelcomeTour component or null.
  */
 function WelcomeTour() {
 	const [ showDraftPostModal ] = useState(

projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/first-post-published-modal/index.tsx

@@ -19,6 +19,7 @@ type CoreEditorPlaceholder = {
 
 /**
  * Show the first post publish modal
+ * @return {JSX.Element | null} The modal component or null.
  */
 const FirstPostPublishedModalInner: React.FC = () => {
 	const { link } = useSelect(

projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/purchase-notice/index.jsx

@@ -6,6 +6,7 @@ import './style.scss';
 
 /**
  * Display the purchase notice snackbar
+ * @return {null} This component is non-rendering.
  */
 function PurchaseNotice() {
 	const hasPaymentNotice = useRef( false );

projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/recommended-tags-modal/suggested-tags.tsx

@@ -37,9 +37,10 @@ type SuggestedTagsProps = {
 /**
  * Display the suggested tags.
  *
- * @param props - The props of the component.
+ * @param  props - The props of the component.
+ * @return {JSX.Element} The SuggestedTags component.
  */
-function SuggestedTags( props: SuggestedTagsProps ) {
+function SuggestedTags( props: SuggestedTagsProps ): JSX.Element {
 	const localeSlug = useLocale();
 	const { id: postId, meta: postMeta } = useSelect(
 		select => ( select( 'core/editor' ) as CoreEditorPlaceholder ).getCurrentPost(),

projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/seller-celebration-modal/index.jsx

@@ -14,6 +14,7 @@ import './style.scss';
 
 /**
  * Show the seller celebration modal
+ * @return {JSX.Element} The modal component.
  */
 const SellerCelebrationModalInner = () => {
 	const { addEntities } = useDispatch( 'core' );

projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/store.js

@@ -138,6 +138,8 @@ export const selectors = {
 
 /**
  * Register the wpcom-welcome-guide store
+ *
+ * @return {object} The registered store.
  */
 export function register() {
 	return registerStore( 'automattic/wpcom-welcome-guide', {

projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/welcome-modal/wpcom-nux.js

@@ -12,6 +12,7 @@ import './style.scss';
 
 /**
  * The nux component.
+ * @return {JSX.Element} The WpcomNux component or null.
  */
 function WpcomNux() {
 	const { show, isNewPageLayoutModalOpen, isManuallyOpened } = useSelect( select => ( {
@@ -113,13 +114,14 @@ function getWpcomNuxPages() {
 /**
  * Display the Nux page
  *
- * @param props             - The props of the component.
- * @param props.pageNumber  - The number of page.
- * @param props.isLastPage  - Whether the current page is the last one.
- * @param props.alignBottom - Whether to align bottom.
- * @param props.heading     - The text of heading.
- * @param props.description - The text of description.
- * @param props.imgSrc      - The src of image.
+ * @param {object}  props                     - The props of the component.
+ * @param {number}  props.pageNumber          - The number of page.
+ * @param {boolean} props.isLastPage          - Whether the current page is the last one.
+ * @param {boolean} [props.alignBottom=false] - Whether to align bottom.
+ * @param {string}  props.heading             - The text of heading.
+ * @param {string}  props.description         - The text of description.
+ * @param {string}  props.imgSrc              - The src of image.
+ * @return {JSX.Element} The NuxPage component.
  */
 function NuxPage( { pageNumber, isLastPage, alignBottom = false, heading, description, imgSrc } ) {
 	useEffect( () => {

projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/welcome-tour/tour-launch.jsx

@@ -16,6 +16,8 @@ import './style-tour.scss';
 
 /**
  * The Welcome Tour of the Launch.
+ *
+ * @return {JSX.Element|null} The welcome tour component or null.
  */
 function LaunchWpcomWelcomeTour() {
 	const { show, isNewPageLayoutModalOpen, isManuallyOpened } = useSelect(
@@ -80,8 +82,9 @@ function LaunchWpcomWelcomeTour() {
 /**
  * Display the welcome tour.
  *
- * @param props            - The props of the component.
- * @param props.siteIntent - The intent of the site.
+ * @param {object} props            - The props of the component.
+ * @param {string} props.siteIntent - The intent of the site.
+ * @return {JSX.Element|null} The WelcomeTour component if a theme name is found, otherwise null.
  */
 function WelcomeTour( { siteIntent } ) {
 	const sitePlan = useSitePlan( window._currentSiteId );

projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/welcome-tour/use-tour-steps.tsx

@@ -17,7 +17,8 @@ interface TourAsset {
 /**
  * Get the tour asset by the key.
  *
- * @param key - The key of the tour asset.
+ * @param  key - The key of the tour asset.
+ * @return {TourAsset | undefined} The requested tour asset, or undefined if not found.
  */
 function getTourAssets( key: string ): TourAsset | undefined {
 	const CDN_PREFIX = 'https://s0.wp.com/i/editor-welcome-tour';
@@ -69,11 +70,12 @@ function getTourAssets( key: string ): TourAsset | undefined {
 /**
  * Get the steps of the tour
  *
- * @param localeSlug           - The slug of the locale.
- * @param referencePositioning - The reference positioning.
- * @param isSiteEditor         - Whether is the site editor.
- * @param themeName            - The name of the theme.
- * @param siteIntent           - The intent of the current site.
+ * @param  localeSlug           - The slug of the locale.
+ * @param  referencePositioning - The reference positioning.
+ * @param  isSiteEditor         - Whether is the site editor.
+ * @param  themeName            - The name of the theme.
+ * @param  siteIntent           - The intent of the current site.
+ * @return {WpcomStep[]} The steps of the tour.
  */
 function useTourSteps(
 	localeSlug: string,