diff --git a/projects/packages/jetpack-mu-wpcom/bin/sync-newspack-blocks-formatter.js b/projects/packages/jetpack-mu-wpcom/bin/sync-newspack-blocks-formatter.js index 2f1b818dcb694..cf4ada09165fe 100644 --- a/projects/packages/jetpack-mu-wpcom/bin/sync-newspack-blocks-formatter.js +++ b/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 ( diff --git a/projects/packages/jetpack-mu-wpcom/changelog/fix-jetpack-mu-wpcom-eslint_fixes b/projects/packages/jetpack-mu-wpcom/changelog/fix-jetpack-mu-wpcom-eslint_fixes new file mode 100644 index 0000000000000..812b9286ccba6 --- /dev/null +++ b/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. diff --git a/projects/packages/jetpack-mu-wpcom/eslint.config.mjs b/projects/packages/jetpack-mu-wpcom/eslint.config.mjs index 5c87cf0cf46f2..7f678302d6651 100644 --- a/projects/packages/jetpack-mu-wpcom/eslint.config.mjs +++ b/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', }, }, { diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/keyboard-navigation.tsx b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/keyboard-navigation.tsx index 002a3a3ad050c..3e18585542e78 100644 --- a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/keyboard-navigation.tsx +++ b/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; diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-focus-handler.ts b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-focus-handler.ts index 3054fb2253e8c..aebbc54a6a10c 100644 --- a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-focus-handler.ts +++ b/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 ); diff --git a/projects/packages/jetpack-mu-wpcom/src/features/block-inserter-modifications/src/contextual-tip.js b/projects/packages/jetpack-mu-wpcom/src/features/block-inserter-modifications/src/contextual-tip.js index 76bb0d696d843..efc9517890e67 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/block-inserter-modifications/src/contextual-tip.js +++ b/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 ) { diff --git a/projects/packages/jetpack-mu-wpcom/src/features/block-inserter-modifications/src/list.js b/projects/packages/jetpack-mu-wpcom/src/features/block-inserter-modifications/src/list.js index c1dbf8b3e620f..4ef4bb23eba10 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/block-inserter-modifications/src/list.js +++ b/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} 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' ) { diff --git a/projects/packages/jetpack-mu-wpcom/src/features/block-inserter-modifications/src/tip-link.js b/projects/packages/jetpack-mu-wpcom/src/features/block-inserter-modifications/src/tip-link.js index da71674594f02..60d9f53eddb49 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/block-inserter-modifications/src/tip-link.js +++ b/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; diff --git a/projects/packages/jetpack-mu-wpcom/src/features/block-theme-previews/modal.jsx b/projects/packages/jetpack-mu-wpcom/src/features/block-theme-previews/modal.jsx index b57f7b1837874..7390de6d4e0a6 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/block-theme-previews/modal.jsx +++ b/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(); diff --git a/projects/packages/jetpack-mu-wpcom/src/features/block-theme-previews/utils.js b/projects/packages/jetpack-mu-wpcom/src/features/block-theme-previews/utils.js index 919d4c74e7d02..dd58d85e5f31f 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/block-theme-previews/utils.js +++ b/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' ); diff --git a/projects/packages/jetpack-mu-wpcom/src/features/jetpack-global-styles/customizer-fonts/index.js b/projects/packages/jetpack-mu-wpcom/src/features/jetpack-global-styles/customizer-fonts/index.js index 3490ce437f45f..55e9b60433d73 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/jetpack-global-styles/customizer-fonts/index.js +++ b/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 || []; diff --git a/projects/packages/jetpack-mu-wpcom/src/features/newspack-blocks/blog-posts/editor.js b/projects/packages/jetpack-mu-wpcom/src/features/newspack-blocks/blog-posts/editor.js index 747ad9a856587..895201345ff96 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/newspack-blocks/blog-posts/editor.js +++ b/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; diff --git a/projects/packages/jetpack-mu-wpcom/src/features/newspack-blocks/carousel/editor.js b/projects/packages/jetpack-mu-wpcom/src/features/newspack-blocks/carousel/editor.js index 5bef920682dc0..1e150d1118705 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/newspack-blocks/carousel/editor.js +++ b/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; diff --git a/projects/packages/jetpack-mu-wpcom/src/features/starter-page-templates/page-patterns-plugin.tsx b/projects/packages/jetpack-mu-wpcom/src/features/starter-page-templates/page-patterns-plugin.tsx index 5416ef359984b..9d712bef5b6e9 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/starter-page-templates/page-patterns-plugin.tsx +++ b/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' ); diff --git a/projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/src/components/FrequencyToggle/index.tsx b/projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/src/components/FrequencyToggle/index.tsx index 822b0a8a442e3..fa48f104922d3 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/src/components/FrequencyToggle/index.tsx +++ b/projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/src/components/FrequencyToggle/index.tsx @@ -23,6 +23,7 @@ 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', @@ -30,7 +31,7 @@ export function FrequencyToggle( { onChange, selectedOption, disabled, -}: FrequencyToggleProps ) { +}: FrequencyToggleProps ): JSX.Element { return (
diff --git a/projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/src/components/logged-in.tsx b/projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/src/components/logged-in.tsx index 6021400b71c2b..fe5bea9284e86 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/src/components/logged-in.tsx +++ b/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 ); } diff --git a/projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/src/hooks/useSubscriptionApi.tsx b/projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/src/hooks/useSubscriptionApi.tsx index 5e9de6bcd8b7b..0fd1b1660bdbb 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/src/hooks/useSubscriptionApi.tsx +++ b/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 ); diff --git a/projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/src/i18n.ts b/projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/src/i18n.ts index 52820f6096925..e532b3155af89 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/src/i18n.ts +++ b/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; } diff --git a/projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/src/utils.ts b/projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/src/utils.ts index 8041dafa7ff2d..9a28d20fb0291 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/src/utils.ts +++ b/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; diff --git a/projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/tests/utils.ts b/projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/tests/utils.ts index eb7d843a2cf6f..880401aa6091c 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/verbum-comments/tests/utils.ts +++ b/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 ) ] ); diff --git a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-description-links/src/inline-support-link.tsx b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-description-links/src/inline-support-link.tsx index 3a1ac7f660650..acc427db85892 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-description-links/src/inline-support-link.tsx +++ b/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, diff --git a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/block-editor-nux.js b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/block-editor-nux.js index 449ea75aeaf8f..862a8fe088887 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/block-editor-nux.js +++ b/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( diff --git a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/first-post-published-modal/index.tsx b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/first-post-published-modal/index.tsx index 039a89165ea51..d489e94d60b37 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/first-post-published-modal/index.tsx +++ b/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( diff --git a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/purchase-notice/index.jsx b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/purchase-notice/index.jsx index b6ffafa4ab99d..0d24231d02817 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/purchase-notice/index.jsx +++ b/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 ); diff --git a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/recommended-tags-modal/suggested-tags.tsx b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/recommended-tags-modal/suggested-tags.tsx index a60376a29a19b..92b8598f442f2 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/recommended-tags-modal/suggested-tags.tsx +++ b/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(), diff --git a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/seller-celebration-modal/index.jsx b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/seller-celebration-modal/index.jsx index b31b774ea4e6b..53a9f115897a4 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/seller-celebration-modal/index.jsx +++ b/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' ); diff --git a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/store.js b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/store.js index 6cc4da7c641eb..0aad72e40e43c 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/store.js +++ b/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', { diff --git a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/welcome-modal/wpcom-nux.js b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/welcome-modal/wpcom-nux.js index 535833b504b64..828df3697d86a 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/welcome-modal/wpcom-nux.js +++ b/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( () => { diff --git a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/welcome-tour/tour-launch.jsx b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/welcome-tour/tour-launch.jsx index 6789b4e5ed931..277353f9864aa 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/welcome-tour/tour-launch.jsx +++ b/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 ); diff --git a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/welcome-tour/use-tour-steps.tsx b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/welcome-tour/use-tour-steps.tsx index 93035417edd44..c9b77845c51b2 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-block-editor-nux/src/welcome-tour/use-tour-steps.tsx +++ b/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, diff --git a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-blocks/event-countdown/view.js b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-blocks/event-countdown/view.js index d17346aa9b3a0..a792b3857dc7c 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-blocks/event-countdown/view.js +++ b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-blocks/event-countdown/view.js @@ -6,7 +6,8 @@ domReady( function () { /** * Test whether the value is unix timestamp or not. * - * @param dtstr - the value to test + * @param {string} dtstr - The value to test + * @return {boolean} True if the value contains only numbers, otherwise false. */ function isUnixTimestamp( dtstr ) { return /^[0-9]+$/.test( dtstr ); @@ -50,9 +51,9 @@ domReady( function () { * Countdown element passed in as the dom node to search * within, supporting multiple events per page * - * @param ts - The timestamp of the countdown - * @param elem - The element of the countdown container - * @param id - The ID of the countdown + * @param {number} ts - The timestamp of the countdown + * @param {HTMLElement} elem - The element of the countdown container + * @param {number} id - The ID of the countdown interval */ function updateCountdown( ts, elem, id ) { const now = Date.now(); @@ -89,7 +90,7 @@ domReady( function () { * the majority of views will be well after and * not during the transition * - * @param elem - The element of the countdown container + * @param {HTMLElement} elem - The element of the countdown container */ function itsHappening( elem ) { const countdown = elem.getElementsByClassName( 'event-countdown__counter' )[ 0 ]; diff --git a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-documentation-links/wpcom-documentation-links.ts b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-documentation-links/wpcom-documentation-links.ts index ee1c306b27205..7eb9162c8fb60 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-documentation-links/wpcom-documentation-links.ts +++ b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-documentation-links/wpcom-documentation-links.ts @@ -5,10 +5,11 @@ import './wpcom-documentation-links.css'; /** * Override Core documentation that has matching WordPress.com documentation. * - * @param translation - string Translated text. - * @param text - string Original text. + * @param {string} translation - string Translated text. + * @param {string} text - string Original text. + * @return {string} - The localized URL if a match is found, otherwise the original translation. */ -function overrideCoreDocumentationLinksToWpcom( translation: string, text: string ) { +function overrideCoreDocumentationLinksToWpcom( translation: string, text: string ): string { const documentLinksMap = { /** * Excerpts @@ -73,10 +74,11 @@ function overrideCoreDocumentationLinksToWpcom( translation: string, text: strin /** * Override Core documentation that doesn't have matching WordPress.com documentation. * - * @param translation - string Translated text. - * @param text - string Original text. + * @param {string} translation - string Translated text. + * @param {string} text - string Original text. + * @return {string} - Empty string for specific text, otherwise translated string. */ -function hideSimpleSiteTranslations( translation: string, text: string ) { +function hideSimpleSiteTranslations( translation: string, text: string ): string { switch ( text ) { case 'https://wordpress.org/plugins/classic-widgets/': return ''; diff --git a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-global-styles/notices.js b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-global-styles/notices.js index 31efc641857d5..16cd184be1ac0 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-global-styles/notices.js +++ b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-global-styles/notices.js @@ -28,6 +28,8 @@ const trackEvent = ( eventName, isSiteEditor = true ) => /** * Limited GS notice for the view canvas of the site editor. + * + * @return {JSX.Element} The component to render. */ function GlobalStylesWarningNotice() { useEffect( () => { @@ -63,6 +65,8 @@ function GlobalStylesWarningNotice() { /** * Renders a notice in the view canvas of the site editor when GS are limited. + * + * @return {null} This component is non-rendering. */ function GlobalStylesViewNotice() { const { canvas } = useCanvas(); @@ -105,6 +109,8 @@ function GlobalStylesViewNotice() { /** * Limited GS notice for the edit view of the site editor. + * + * @return {null} This component is non-rendering. */ function GlobalStylesEditNotice() { const NOTICE_ID = 'wpcom-global-styles/gating-notice'; @@ -251,6 +257,8 @@ function GlobalStylesEditNotice() { /** * Limited GS notices for the site editor. + * + * @return {JSX.Element} The component to render. */ export default function GlobalStylesNotices() { return ( diff --git a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-global-styles/use-canvas.js b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-global-styles/use-canvas.js index 931e83f46922d..d5f3e838a5ea8 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-global-styles/use-canvas.js +++ b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-global-styles/use-canvas.js @@ -3,6 +3,8 @@ import { useEffect, useState } from '@wordpress/element'; /** * Custom hook to detect the current canvas (view or edit) of the site editor. + * + * @return {object} An object containing the current canvas and viewCanvasPath. */ export function useCanvas() { const [ canvas, setCanvas ] = useState(); diff --git a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-global-styles/use-global-styles-config.js b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-global-styles/use-global-styles-config.js index 4d46314022561..4f0aad8ce0a47 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-global-styles/use-global-styles-config.js +++ b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-global-styles/use-global-styles-config.js @@ -2,6 +2,8 @@ import { useSelect } from '@wordpress/data'; /** * Custom hook to detect whether Global Styles are in use. + * + * @return {object} An object containing globalStylesInUse and globalStylesId. */ export function useGlobalStylesConfig() { return useSelect( select => { diff --git a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-global-styles/use-preview.js b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-global-styles/use-preview.js index ef4cef034e0ee..4a44d4a683308 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-global-styles/use-preview.js +++ b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-global-styles/use-preview.js @@ -6,7 +6,7 @@ import { addQueryArgs } from '@wordpress/url'; /** * Displays a loading placeholder before generating a preview in a given HTML document. - * @param targetDocument - {HTMLDocument} The HTML document. + * @param {Document} targetDocument - The HTML document. */ function writeInterstitialMessage( targetDocument ) { let markup = renderToString( @@ -89,6 +89,7 @@ function writeInterstitialMessage( targetDocument ) { /** * Custom hook to preview a site without custom Global Styles applied. + * @return {object} An object containing the previewPostWithoutCustomStyles function and canPreviewPost boolean. */ export function usePreview() { const { diff --git a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-global-styles/wpcom-global-styles-view.js b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-global-styles/wpcom-global-styles-view.js index e0544227ad5cd..00620574d9ce3 100644 --- a/projects/packages/jetpack-mu-wpcom/src/features/wpcom-global-styles/wpcom-global-styles-view.js +++ b/projects/packages/jetpack-mu-wpcom/src/features/wpcom-global-styles/wpcom-global-styles-view.js @@ -5,8 +5,8 @@ import './wpcom-global-styles-view.scss'; /** * Records a Tracks click event. - * @param button - {string} Identifier of the button that has been clicked. - * @param props - {object} Additional props to track. + * @param {string} button - Identifier of the button that has been clicked. + * @param {object} props - Additional props to track. */ function recordEvent( button, props = {} ) { wpcomTrackEvent( 'wpcom_launchbar_button_click', { diff --git a/projects/packages/jetpack-mu-wpcom/webpack.config.js b/projects/packages/jetpack-mu-wpcom/webpack.config.js index d344e35cfc254..7245700ce8b32 100644 --- a/projects/packages/jetpack-mu-wpcom/webpack.config.js +++ b/projects/packages/jetpack-mu-wpcom/webpack.config.js @@ -125,6 +125,7 @@ module.exports = [ * Note this is not the same as looking for `__dirname+'/node_modules/'+pkgName`, as the package may be in a parent * `node_modules` * @param {string} pkgName - Name of the package to search for. + * @return {string} - The absolute path of the package. */ function findPackage( pkgName ) { const fullPath = require.resolve( pkgName );