diff --git a/bin/packages/build-worker.js b/bin/packages/build-worker.js index e0de0fd401181..0feed9e91bbe9 100644 --- a/bin/packages/build-worker.js +++ b/bin/packages/build-worker.js @@ -54,7 +54,7 @@ const renderSass = promisify( sass.render ); /** * Get the package name for a specified file * - * @param {string} file File name + * @param {string} file File name * @return {string} Package name */ function getPackageName( file ) { @@ -64,8 +64,8 @@ function getPackageName( file ) { /** * Get Build Path for a specified file. * - * @param {string} file File to build - * @param {string} buildFolder Output folder + * @param {string} file File to build + * @param {string} buildFolder Output folder * @return {string} Build path */ function getBuildPath( file, buildFolder ) { diff --git a/bin/packages/build.js b/bin/packages/build.js index fa837de240ea8..69600530f4b23 100755 --- a/bin/packages/build.js +++ b/bin/packages/build.js @@ -19,7 +19,7 @@ const PACKAGES_DIR = path.resolve( __dirname, '../../packages' ); /** * Get the package name for a specified file * - * @param {string} file File name + * @param {string} file File name * @return {string} Package name */ function getPackageName( file ) { diff --git a/bin/plugin/commands/packages.js b/bin/plugin/commands/packages.js index 9a16beeb82b06..cedf3c640e070 100644 --- a/bin/plugin/commands/packages.js +++ b/bin/plugin/commands/packages.js @@ -86,10 +86,10 @@ async function runWordPressReleaseBranchSyncStep( * Update CHANGELOG files with the new version number for those packages that * contain new entries. * - * @param {string} gitWorkingDirectoryPath Git working directory path. - * @param {string} minimumVersionBump Minimum version bump for the packages. - * @param {boolean} isPrerelease Whether the package version to publish is a prerelease. - * @param {string} abortMessage Abort Message. + * @param {string} gitWorkingDirectoryPath Git working directory path. + * @param {string} minimumVersionBump Minimum version bump for the packages. + * @param {boolean} isPrerelease Whether the package version to publish is a prerelease. + * @param {string} abortMessage Abort Message. */ async function updatePackages( gitWorkingDirectoryPath, @@ -274,8 +274,8 @@ async function runPushGitChangesStep( /** * Prepare everything to publish WordPress packages to npm. * - * @param {string} minimumVersionBump Minimum version bump for the packages. - * @param {boolean} isPrerelease Whether the package version to publish is a prerelease. + * @param {string} minimumVersionBump Minimum version bump for the packages. + * @param {boolean} isPrerelease Whether the package version to publish is a prerelease. * * @return {Promise} Github release object. */ diff --git a/bin/plugin/commands/performance.js b/bin/plugin/commands/performance.js index f271e66268a6f..1b7038c375d93 100644 --- a/bin/plugin/commands/performance.js +++ b/bin/plugin/commands/performance.js @@ -27,32 +27,32 @@ const config = require( '../config' ); /** * @typedef WPRawPerformanceResults * - * @property {number[]} load Load Time. - * @property {number[]} type Average type time. - * @property {number[]} focus Average block selection time. + * @property {number[]} load Load Time. + * @property {number[]} type Average type time. + * @property {number[]} focus Average block selection time. */ /** * @typedef WPPerformanceResults * - * @property {number} load Load Time. - * @property {number} type Average type time. - * @property {number} minType Minium type time. - * @property {number} maxType Maximum type time. - * @property {number} focus Average block selection time. - * @property {number} minFocus Min block selection time. - * @property {number} maxFocus Max block selection time. + * @property {number} load Load Time. + * @property {number} type Average type time. + * @property {number} minType Minium type time. + * @property {number} maxType Maximum type time. + * @property {number} focus Average block selection time. + * @property {number} minFocus Min block selection time. + * @property {number} maxFocus Max block selection time. */ /** * @typedef WPFormattedPerformanceResults * - * @property {string=} load Load Time. - * @property {string=} type Average type time. - * @property {string=} minType Minium type time. - * @property {string=} maxType Maximum type time. - * @property {string=} focus Average block selection time. - * @property {string=} minFocus Min block selection time. - * @property {string=} maxFocus Max block selection time. + * @property {string=} load Load Time. + * @property {string=} type Average type time. + * @property {string=} minType Minium type time. + * @property {string=} maxType Maximum type time. + * @property {string=} focus Average block selection time. + * @property {string=} minFocus Min block selection time. + * @property {string=} maxFocus Max block selection time. */ /** @@ -115,8 +115,8 @@ function curateResults( results ) { /** * Set up the given branch for testing. * - * @param {string} branch Branch name. - * @param {string} environmentDirectory Path to the plugin environment's clone. + * @param {string} branch Branch name. + * @param {string} environmentDirectory Path to the plugin environment's clone. */ async function setUpGitBranch( branch, environmentDirectory ) { // Restore clean working directory (e.g. if `package-lock.json` has local @@ -179,8 +179,8 @@ async function runTestSuite( testSuite, performanceTestDirectory ) { /** * Runs the performances tests on an array of branches and output the result. * - * @param {WPPerformanceCommandOptions} options Command options. - * @param {string[]} branches Branches to compare + * @param {string[]} branches Branches to compare. + * @param {WPPerformanceCommandOptions} options Command options. */ async function runPerformanceTests( branches, options ) { // The default value doesn't work because commander provides an array. diff --git a/bin/plugin/commands/release.js b/bin/plugin/commands/release.js index 9df33d8987b07..0bee800b933f6 100644 --- a/bin/plugin/commands/release.js +++ b/bin/plugin/commands/release.js @@ -112,7 +112,7 @@ async function runReleaseBranchCreationStep( * Checkouts out the release branch and chooses a stable version number. * * @param {string} gitWorkingDirectoryPath Git Working Directory Path. - * @param {string} abortMessage Abort Message. + * @param {string} abortMessage Abort Message. * * @return {Promise} chosen version and versionLabels. */ @@ -384,8 +384,8 @@ async function runPushGitChangesStep( * Cherry-picks the version bump commit into master. * * @param {string} gitWorkingDirectoryPath Git Working Directory Path. - * @param {string} commitHash Commit to cherry-pick. - * @param {string} abortMessage Abort message. + * @param {string} commitHash Commit to cherry-pick. + * @param {string} abortMessage Abort message. */ async function runCherrypickBumpCommitIntoMasterStep( gitWorkingDirectoryPath, @@ -419,12 +419,12 @@ async function runCherrypickBumpCommitIntoMasterStep( /** * Creates the github release and uploads the ZIP file into it. * - * @param {string} zipPath Plugin zip path. - * @param {string} version Released version. - * @param {string} versionLabel Label of the released Version. - * @param {string} changelog Release changelog. - * @param {boolean} isPrerelease is a pre-release. - * @param {string} abortMessage Abort message. + * @param {string} zipPath Plugin zip path. + * @param {string} version Released version. + * @param {string} versionLabel Label of the released Version. + * @param {string} changelog Release changelog. + * @param {boolean} isPrerelease is a pre-release. + * @param {string} abortMessage Abort message. * * @return {Promise} Github release object. */ @@ -565,8 +565,8 @@ async function runUpdateTrunkContentStep( /** * Creates a new SVN Tag * - * @param {string} version Version. - * @param {string} abortMessage Abort Message. + * @param {string} version Version. + * @param {string} abortMessage Abort Message. */ async function runSvnTagStep( version, abortMessage ) { await runStep( 'Creating the SVN Tag', abortMessage, async () => { diff --git a/bin/plugin/config.js b/bin/plugin/config.js index e920af08cdc57..9f93048d02a16 100644 --- a/bin/plugin/config.js +++ b/bin/plugin/config.js @@ -3,20 +3,20 @@ const gitRepoOwner = 'WordPress'; /** * @typedef WPPluginCLIConfig * - * @property {string} slug Slug. - * @property {string} name Name. - * @property {string} team Github Team Name. - * @property {string} versionMilestoneFormat printf template for milestone + * @property {string} slug Slug. + * @property {string} name Name. + * @property {string} team Github Team Name. + * @property {string} versionMilestoneFormat printf template for milestone * version name. Expected to be called * with a merged object of the config * and semver-parsed version parts. - * @property {string} githubRepositoryOwner Github Repository Owner. - * @property {string} githubRepositoryName Github Repository Name. - * @property {string} pluginEntryPoint Plugin Entry Point File. - * @property {string} buildZipCommand Build Plugin ZIP command. + * @property {string} githubRepositoryOwner Github Repository Owner. + * @property {string} githubRepositoryName Github Repository Name. + * @property {string} pluginEntryPoint Plugin Entry Point File. + * @property {string} buildZipCommand Build Plugin ZIP command. * @property {string} wpRepositoryReleasesURL WordPress Repository Tags URL. - * @property {string} gitRepositoryURL Git Repository URL. - * @property {string} svnRepositoryURL SVN Repository URL. + * @property {string} gitRepositoryURL Git Repository URL. + * @property {string} svnRepositoryURL SVN Repository URL. */ /** diff --git a/bin/plugin/lib/git.js b/bin/plugin/lib/git.js index b8b4242800744..338c0ca896a8c 100644 --- a/bin/plugin/lib/git.js +++ b/bin/plugin/lib/git.js @@ -28,9 +28,9 @@ async function clone( repositoryUrl ) { /** * Commits changes to the repository. * - * @param {string} gitWorkingDirectoryPath Local repository path. - * @param {string} message Commit message. - * @param {string[]} filesToAdd Files to add. + * @param {string} gitWorkingDirectoryPath Local repository path. + * @param {string} message Commit message. + * @param {string[]} filesToAdd Files to add. * * @return {Promise} Commit Hash */ @@ -47,7 +47,7 @@ async function commit( gitWorkingDirectoryPath, message, filesToAdd = [] ) { * Creates a local branch. * * @param {string} gitWorkingDirectoryPath Local repository path. - * @param {string} branchName Branch Name + * @param {string} branchName Branch Name */ async function createLocalBranch( gitWorkingDirectoryPath, branchName ) { const simpleGit = SimpleGit( gitWorkingDirectoryPath ); @@ -58,7 +58,7 @@ async function createLocalBranch( gitWorkingDirectoryPath, branchName ) { * Checkout a local branch. * * @param {string} gitWorkingDirectoryPath Local repository path. - * @param {string} branchName Branch Name + * @param {string} branchName Branch Name */ async function checkoutRemoteBranch( gitWorkingDirectoryPath, branchName ) { const simpleGit = SimpleGit( gitWorkingDirectoryPath ); @@ -70,7 +70,7 @@ async function checkoutRemoteBranch( gitWorkingDirectoryPath, branchName ) { * Creates a local tag. * * @param {string} gitWorkingDirectoryPath Local repository path. - * @param {string} tagName Tag Name + * @param {string} tagName Tag Name */ async function createLocalTag( gitWorkingDirectoryPath, tagName ) { const simpleGit = SimpleGit( gitWorkingDirectoryPath ); @@ -81,7 +81,7 @@ async function createLocalTag( gitWorkingDirectoryPath, tagName ) { * Pushes a local branch to the origin. * * @param {string} gitWorkingDirectoryPath Local repository path. - * @param {string} branchName Branch Name + * @param {string} branchName Branch Name */ async function pushBranchToOrigin( gitWorkingDirectoryPath, branchName ) { const simpleGit = SimpleGit( gitWorkingDirectoryPath ); @@ -112,7 +112,7 @@ async function discardLocalChanges( gitWorkingDirectoryPath ) { * Reset local branch against the origin. * * @param {string} gitWorkingDirectoryPath Local repository path. - * @param {string} branchName Branch Name + * @param {string} branchName Branch Name */ async function resetLocalBranchAgainstOrigin( gitWorkingDirectoryPath, @@ -128,7 +128,7 @@ async function resetLocalBranchAgainstOrigin( * Cherry-picks a commit into master * * @param {string} gitWorkingDirectoryPath Local repository path. - * @param {string} commitHash Branch Name + * @param {string} commitHash Branch Name */ async function cherrypickCommitIntoBranch( gitWorkingDirectoryPath, @@ -143,7 +143,7 @@ async function cherrypickCommitIntoBranch( * Replaces the local branch's content with the content from another branch. * * @param {string} gitWorkingDirectoryPath Local repository path. - * @param {string} sourceBranchName Branch Name + * @param {string} sourceBranchName Branch Name */ async function replaceContentFromRemoteBranch( gitWorkingDirectoryPath, diff --git a/bin/plugin/lib/utils.js b/bin/plugin/lib/utils.js index 2acebd804cf95..91094c6fb0737 100644 --- a/bin/plugin/lib/utils.js +++ b/bin/plugin/lib/utils.js @@ -17,8 +17,8 @@ const { log, formats } = require( './logger' ); /** * Utility to run a child script * - * @param {string} script Script to run. - * @param {string=} cwd Working directory. + * @param {string} script Script to run. + * @param {string=} cwd Working directory. */ function runShellScript( script, cwd ) { childProcess.execSync( script, { @@ -45,9 +45,9 @@ function readJSONFile( fileName ) { /** * Common logic wrapping a step in the process. * - * @param {string} name Step name. - * @param {string} abortMessage Abort message. - * @param {Function} handler Step logic. + * @param {string} name Step name. + * @param {string} abortMessage Abort message. + * @param {Function} handler Step logic. */ async function runStep( name, abortMessage, handler ) { try { @@ -70,9 +70,9 @@ async function runStep( name, abortMessage, handler ) { /** * Asks the user for a confirmation to continue or abort otherwise. * - * @param {string} message Confirmation message. - * @param {boolean} isDefault Default reply. - * @param {string} abortMessage Abort message. + * @param {string} message Confirmation message. + * @param {boolean} isDefault Default reply. + * @param {string} abortMessage Abort message. */ async function askForConfirmation( message, diff --git a/packages/a11y/src/index.js b/packages/a11y/src/index.js index ba05af819a533..957c76500c434 100644 --- a/packages/a11y/src/index.js +++ b/packages/a11y/src/index.js @@ -43,7 +43,7 @@ domReady( setup ); * Allows you to easily announce dynamic interface updates to screen readers using ARIA live regions. * This module is inspired by the `speak` function in `wp-a11y.js`. * - * @param {string} message The message to be announced by assistive technologies. + * @param {string} message The message to be announced by assistive technologies. * @param {string} [ariaLive] The politeness level for aria-live; default: 'polite'. * * @example diff --git a/packages/a11y/src/index.native.js b/packages/a11y/src/index.native.js index 41a6591d34516..419633351a751 100644 --- a/packages/a11y/src/index.native.js +++ b/packages/a11y/src/index.native.js @@ -6,7 +6,7 @@ import filterMessage from './filter-message'; /** * Update the ARIA live notification area text node. * - * @param {string} message The message to be announced by Assistive Technologies. + * @param {string} message The message to be announced by Assistive Technologies. * @param {string} [ariaLive] The politeness level for aria-live; default: 'polite'. */ export function speak( message, ariaLive ) { diff --git a/packages/annotations/src/format/annotation.js b/packages/annotations/src/format/annotation.js index 9ce2a2bd6d456..6a91631eb39aa 100644 --- a/packages/annotations/src/format/annotation.js +++ b/packages/annotations/src/format/annotation.js @@ -12,8 +12,8 @@ const STORE_KEY = 'core/annotations'; /** * Applies given annotations to the given record. * - * @param {Object} record The record to apply annotations to. - * @param {Array} annotations The annotation to apply. + * @param {Object} record The record to apply annotations to. + * @param {Array} annotations The annotation to apply. * @return {Object} A record with the annotations applied. */ export function applyAnnotations( record, annotations = [] ) { diff --git a/packages/annotations/src/store/actions.js b/packages/annotations/src/store/actions.js index e6f1e5b409dd0..6fe017e2eb9c1 100644 --- a/packages/annotations/src/store/actions.js +++ b/packages/annotations/src/store/actions.js @@ -72,8 +72,8 @@ export function __experimentalRemoveAnnotation( annotationId ) { * Updates the range of an annotation. * * @param {string} annotationId ID of the annotation to update. - * @param {number} start The start of the new range. - * @param {number} end The end of the new range. + * @param {number} start The start of the new range. + * @param {number} end The end of the new range. * * @return {Object} Action object. */ diff --git a/packages/annotations/src/store/selectors.js b/packages/annotations/src/store/selectors.js index fd5a2d2fccfaf..299d637f41c1e 100644 --- a/packages/annotations/src/store/selectors.js +++ b/packages/annotations/src/store/selectors.js @@ -18,7 +18,7 @@ const EMPTY_ARRAY = []; /** * Returns the annotations for a specific client ID. * - * @param {Object} state Editor state. + * @param {Object} state Editor state. * @param {string} clientId The ID of the block to get the annotations for. * * @return {Array} The annotations applicable to this block. diff --git a/packages/autop/src/index.js b/packages/autop/src/index.js index 47e43b0389f95..38d2c907293d9 100644 --- a/packages/autop/src/index.js +++ b/packages/autop/src/index.js @@ -51,7 +51,7 @@ const htmlSplitRegex = ( () => { /** * Separate HTML elements and comments from the text. * - * @param {string} input The text which has to be formatted. + * @param {string} input The text which has to be formatted. * @return {string[]} The formatted text. */ function htmlSplit( input ) { @@ -81,8 +81,8 @@ function htmlSplit( input ) { /** * Replace characters or phrases within HTML elements only. * - * @param {string} haystack The text which has to be formatted. - * @param {Record} replacePairs In the form {from: 'to', …}. + * @param {string} haystack The text which has to be formatted. + * @param {Record} replacePairs In the form {from: 'to', …}. * @return {string} The formatted text. */ function replaceInHtmlTags( haystack, replacePairs ) { @@ -123,8 +123,8 @@ function replaceInHtmlTags( haystack, replacePairs ) { * replace double line-breaks with HTML paragraph tags. The remaining line- * breaks after conversion become `
` tags, unless br is set to 'false'. * - * @param {string} text The text which has to be formatted. - * @param {boolean} br Optional. If set, will convert all remaining line- + * @param {string} text The text which has to be formatted. + * @param {boolean} br Optional. If set, will convert all remaining line- * breaks after paragraphing. Default true. * * @example @@ -328,7 +328,7 @@ export function autop( text, br = true ) { * Replaces `

` tags with two line breaks except where the `

` has attributes. * Unifies whitespace. Indents `

  • `, `
    ` and `
    ` for better readability. * - * @param {string} html The content from the editor. + * @param {string} html The content from the editor. * * @example * ```js diff --git a/packages/block-directory/src/store/actions.js b/packages/block-directory/src/store/actions.js index 9f1e96d5db26b..33518c7f917fd 100644 --- a/packages/block-directory/src/store/actions.js +++ b/packages/block-directory/src/store/actions.js @@ -180,7 +180,7 @@ export function removeInstalledBlockType( item ) { /** * Returns an action object used to indicate install in progress * - * @param {string} blockId + * @param {string} blockId * @param {boolean} isInstalling * * @return {Object} Action object. @@ -196,8 +196,8 @@ export function setIsInstalling( blockId, isInstalling ) { /** * Sets an error notice string to be displayed to the user * - * @param {string} blockId The ID of the block plugin. eg: my-block - * @param {string} message The message shown in the notice. + * @param {string} blockId The ID of the block plugin. eg: my-block + * @param {string} message The message shown in the notice. * @param {boolean} isFatal Whether the user can recover from the error * * @return {Object} Action object. diff --git a/packages/block-directory/src/store/selectors.js b/packages/block-directory/src/store/selectors.js index 2d14bb029467f..31de74c88ab5a 100644 --- a/packages/block-directory/src/store/selectors.js +++ b/packages/block-directory/src/store/selectors.js @@ -11,7 +11,7 @@ import hasBlockType from './utils/has-block-type'; /** * Returns true if application is requesting for downloadable blocks. * - * @param {Object} state Global application state. + * @param {Object} state Global application state. * @param {string} filterValue Search string. * * @@ -97,7 +97,7 @@ export const getUnusedBlockTypes = createRegistrySelector( /** * Returns true if application is calling install endpoint. * - * @param {Object} state Global application state. + * @param {Object} state Global application state. * @param {string} blockId Id of the block. * * @return {boolean} Whether its currently installing diff --git a/packages/block-directory/src/store/utils/has-block-type.js b/packages/block-directory/src/store/utils/has-block-type.js index 28274cbd04eec..8f83f40591f0f 100644 --- a/packages/block-directory/src/store/utils/has-block-type.js +++ b/packages/block-directory/src/store/utils/has-block-type.js @@ -2,8 +2,8 @@ * Check if a block list contains a specific block type. Recursively searches * through `innerBlocks` if they exist. * - * @param {Object} blockType A block object to search for. - * @param {Object[]} blocks The list of blocks to look through. + * @param {Object} blockType A block object to search for. + * @param {Object[]} blocks The list of blocks to look through. * * @return {boolean} Whether the blockType is found. */ diff --git a/packages/block-editor/src/autocompleters/block.js b/packages/block-editor/src/autocompleters/block.js index 79cff960e3e71..9eeec8ff75990 100644 --- a/packages/block-editor/src/autocompleters/block.js +++ b/packages/block-editor/src/autocompleters/block.js @@ -38,11 +38,6 @@ const createBlocksFromInnerBlocksTemplate = ( innerBlocksTemplate ) => { /** * Creates a blocks repeater for replacing the current block with a selected block type. * - * @param {Object} props Component props. - * @param {string} [props.getBlockInsertionParentClientId] Client ID of the parent. - * @param {string} [props.getInserterItems] Inserter items for parent. - * @param {string} [props.getSelectedBlockName] Name of selected block or null. - * * @return {WPCompleter} A blocks completer. */ function createBlockCompleter() { diff --git a/packages/block-editor/src/components/block-list/use-multi-selection.js b/packages/block-editor/src/components/block-list/use-multi-selection.js index 2d40464f2c0c5..2372349197a49 100644 --- a/packages/block-editor/src/components/block-list/use-multi-selection.js +++ b/packages/block-editor/src/components/block-list/use-multi-selection.js @@ -14,7 +14,7 @@ import { getBlockClientId, getBlockDOMNode } from '../../utils/dom'; * any text nodes that only contain HTML formatting whitespace. * * @param {Element} node Container to search. - * @param {string} type 'start' or 'end'. + * @param {string} type 'start' or 'end'. */ function getDeepestNode( node, type ) { const child = type === 'start' ? 'firstChild' : 'lastChild'; diff --git a/packages/block-editor/src/components/block-mover/mover-description.js b/packages/block-editor/src/components/block-mover/mover-description.js index fbdc10cb25613..7ac73c3c5fcdb 100644 --- a/packages/block-editor/src/components/block-mover/mover-description.js +++ b/packages/block-editor/src/components/block-mover/mover-description.js @@ -16,7 +16,7 @@ import { __, _n, sprintf } from '@wordpress/i18n'; * down, < 0 is up). * @param {string} orientation The orientation of the block movers, vertical or * horizontal. - * @param {boolean} isRTL True if current writing system is right to left. + * @param {boolean} isRTL True if current writing system is right to left. * * @return {string} Label for the block movement controls. */ diff --git a/packages/block-editor/src/components/block-navigation/use-block-navigation-drop-zone.js b/packages/block-editor/src/components/block-navigation/use-block-navigation-drop-zone.js index 02f541ab63917..9092e4e0edb94 100644 --- a/packages/block-editor/src/components/block-navigation/use-block-navigation-drop-zone.js +++ b/packages/block-editor/src/components/block-navigation/use-block-navigation-drop-zone.js @@ -38,10 +38,10 @@ import useOnBlockDrop from '../use-on-block-drop'; * An object containing details of a drop target. * * @typedef {Object} WPBlockNavigationDropZoneTarget - * @property {string} blockIndex The insertion index. - * @property {string} rootClientId The root client id for the block. - * @property {string|undefined} clientId The client id for the block. - * @property {'top'|'bottom'|'inside'} dropPosition The position relative to the block that the user is dropping to. + * @property {string} blockIndex The insertion index. + * @property {string} rootClientId The root client id for the block. + * @property {string|undefined} clientId The client id for the block. + * @property {'top'|'bottom'|'inside'} dropPosition The position relative to the block that the user is dropping to. * 'inside' refers to nesting as an inner block. */ @@ -170,7 +170,7 @@ const ALLOWED_DROP_EDGES = [ 'top', 'bottom' ]; * Given blocks data and the cursor position, compute the drop target. * * @param {WPBlockNavigationDropZoneBlocks} blocksData Data about the blocks in block navigation. - * @param {WPPoint} position The point representing the cursor position when dragging. + * @param {WPPoint} position The point representing the cursor position when dragging. * * @return {WPBlockNavigationDropZoneTarget} An object containing data about the drop target. */ diff --git a/packages/block-editor/src/components/block-preview/index.js b/packages/block-editor/src/components/block-preview/index.js index 5727d969f34f1..7c223ee108c00 100644 --- a/packages/block-editor/src/components/block-preview/index.js +++ b/packages/block-editor/src/components/block-preview/index.js @@ -50,9 +50,9 @@ export function BlockPreview( { * * @see https://github.com/WordPress/gutenberg/blob/master/packages/block-editor/src/components/block-preview/README.md * - * @param {Object} preview options for how the preview should be shown - * @param {Array|Object} preview.blocks A block instance (object) or an array of blocks to be previewed. - * @param {number} preview.viewportWidth Width of the preview container in pixels. Controls at what size the blocks will be rendered inside the preview. Default: 700. + * @param {Object} preview options for how the preview should be shown + * @param {Array|Object} preview.blocks A block instance (object) or an array of blocks to be previewed. + * @param {number} preview.viewportWidth Width of the preview container in pixels. Controls at what size the blocks will be rendered inside the preview. Default: 700. * * @return {WPComponent} The component to be rendered. */ diff --git a/packages/block-editor/src/components/block-styles/utils.js b/packages/block-editor/src/components/block-styles/utils.js index 9e7c667b2a784..278096085fff0 100644 --- a/packages/block-editor/src/components/block-styles/utils.js +++ b/packages/block-editor/src/components/block-styles/utils.js @@ -10,8 +10,8 @@ import TokenList from '@wordpress/token-list'; /** * Returns the active style from the given className. * - * @param {Array} styles Block style variations. - * @param {string} className Class name + * @param {Array} styles Block style variations. + * @param {string} className Class name * * @return {Object?} The active style. */ diff --git a/packages/block-editor/src/components/colors/utils.js b/packages/block-editor/src/components/colors/utils.js index 903d7033eedee..5c3ede4ad419f 100644 --- a/packages/block-editor/src/components/colors/utils.js +++ b/packages/block-editor/src/components/colors/utils.js @@ -36,8 +36,8 @@ export const getColorObjectByAttributeValues = ( /** * Provided an array of color objects as set by the theme or by the editor defaults, and a color value returns the color object matching that value or undefined. * - * @param {Array} colors Array of color objects as set by the theme or by the editor defaults. - * @param {?string} colorValue A string containing the color value. + * @param {Array} colors Array of color objects as set by the theme or by the editor defaults. + * @param {?string} colorValue A string containing the color value. * * @return {?Object} Color object included in the colors array whose color property equals colorValue. * Returns undefined if no color object matches this requirement. diff --git a/packages/block-editor/src/components/font-sizes/utils.js b/packages/block-editor/src/components/font-sizes/utils.js index 8604e9f287788..1237a13efd7db 100644 --- a/packages/block-editor/src/components/font-sizes/utils.js +++ b/packages/block-editor/src/components/font-sizes/utils.js @@ -33,8 +33,8 @@ export const getFontSize = ( /** * Returns the corresponding font size object for a given value. * - * @param {Array} fontSizes Array of font size objects. - * @param {number} value Font size value. + * @param {Array} fontSizes Array of font size objects. + * @param {number} value Font size value. * * @return {Object} Font size object. */ @@ -52,7 +52,7 @@ export function getFontSizeObjectByValue( fontSizes, value ) { /** * Returns a class based on fontSizeName. * - * @param {string} fontSizeSlug Slug of the fontSize. + * @param {string} fontSizeSlug Slug of the fontSize. * * @return {string} String with the class corresponding to the fontSize passed. * The class is generated by appending 'has-' followed by fontSizeSlug in kebabCase and ending with '-font-size'. diff --git a/packages/block-editor/src/components/gradients/use-gradient.js b/packages/block-editor/src/components/gradients/use-gradient.js index 8e5efdb3b0704..97f2fdff60777 100644 --- a/packages/block-editor/src/components/gradients/use-gradient.js +++ b/packages/block-editor/src/components/gradients/use-gradient.js @@ -24,8 +24,8 @@ export function __experimentalGetGradientClass( gradientSlug ) { /** * Retrieves the gradient value per slug. * - * @param {Array} gradients Gradient Palette - * @param {string} slug Gradient slug + * @param {Array} gradients Gradient Palette + * @param {string} slug Gradient slug * * @return {string} Gradient value. */ @@ -45,8 +45,8 @@ export function __experimentalGetGradientObjectByGradientValue( /** * Retrieves the gradient slug per slug. * - * @param {Array} gradients Gradient Palette - * @param {string} value Gradient value + * @param {Array} gradients Gradient Palette + * @param {string} value Gradient value * @return {string} Gradient slug. */ export function getGradientSlugByValue( gradients, value ) { diff --git a/packages/block-editor/src/components/inner-blocks/use-inner-block-template-sync.js b/packages/block-editor/src/components/inner-blocks/use-inner-block-template-sync.js index 073d50c424c4a..db812ca6cd109 100644 --- a/packages/block-editor/src/components/inner-blocks/use-inner-block-template-sync.js +++ b/packages/block-editor/src/components/inner-blocks/use-inner-block-template-sync.js @@ -17,9 +17,9 @@ import { synchronizeBlocksWithTemplate } from '@wordpress/blocks'; * is meant to be locked (e.g. templateLock = "all"), then we replace the inner * blocks with the correct value after synchronizing it with the template. * - * @param {string} clientId The block client ID. - * @param {Object} template The template to match. - * @param {string} templateLock The template lock state for the inner blocks. For + * @param {string} clientId The block client ID. + * @param {Object} template The template to match. + * @param {string} templateLock The template lock state for the inner blocks. For * example, if the template lock is set to "all", * then the inner blocks will stay in sync with the * template. If not defined or set to false, then diff --git a/packages/block-editor/src/components/inserter/hooks/use-block-types-state.js b/packages/block-editor/src/components/inserter/hooks/use-block-types-state.js index 80cd70ba3013d..ea1bd1e69721f 100644 --- a/packages/block-editor/src/components/inserter/hooks/use-block-types-state.js +++ b/packages/block-editor/src/components/inserter/hooks/use-block-types-state.js @@ -26,8 +26,8 @@ const createBlocksFromInnerBlocksTemplate = ( innerBlocksTemplate ) => { /** * Retrieves the block types inserter state. * - * @param {string=} rootClientId Insertion's root client ID. - * @param {Function} onInsert function called when inserter a list of blocks. + * @param {string=} rootClientId Insertion's root client ID. + * @param {Function} onInsert function called when inserter a list of blocks. * @return {Array} Returns the block types state. (block types, categories, collections, onSelect handler) */ const useBlockTypesState = ( rootClientId, onInsert ) => { diff --git a/packages/block-editor/src/components/link-control/search-input.js b/packages/block-editor/src/components/link-control/search-input.js index c8ae882ae1aba..4ffba74a447b7 100644 --- a/packages/block-editor/src/components/link-control/search-input.js +++ b/packages/block-editor/src/components/link-control/search-input.js @@ -61,7 +61,7 @@ const LinkControlSearchInput = forwardRef( * Handles the user moving between different suggestions. Does not handle * choosing an individual item. * - * @param {string} selection the url of the selected suggestion. + * @param {string} selection the url of the selected suggestion. * @param {Object} suggestion the suggestion object. */ const onInputChange = ( selection, suggestion ) => { diff --git a/packages/block-editor/src/components/provider/use-block-sync.js b/packages/block-editor/src/components/provider/use-block-sync.js index cf07c062b46b4..04a0d6ab42eb8 100644 --- a/packages/block-editor/src/components/provider/use-block-sync.js +++ b/packages/block-editor/src/components/provider/use-block-sync.js @@ -40,25 +40,25 @@ import { useRegistry } from '@wordpress/data'; * controllers. * - Passes selection state from the block-editor store to the controlling entity. * - * @param {Object} props Props for the block sync hook - * @param {string} props.clientId The client ID of the inner block controller. + * @param {Object} props Props for the block sync hook + * @param {string} props.clientId The client ID of the inner block controller. * If none is passed, then it is assumed to be a * root controller rather than an inner block * controller. - * @param {Object[]} props.value The control value for the blocks. This value + * @param {Object[]} props.value The control value for the blocks. This value * is used to initalize the block-editor store * and for resetting the blocks to incoming * changes like undo. - * @param {Object} props.selectionStart The selection start vlaue from the + * @param {Object} props.selectionStart The selection start vlaue from the * controlling component. - * @param {Object} props.selectionEnd The selection end vlaue from the + * @param {Object} props.selectionEnd The selection end vlaue from the * controlling component. - * @param {onBlockUpdate} props.onChange Function to call when a persistent + * @param {onBlockUpdate} props.onChange Function to call when a persistent * change has been made in the block-editor blocks * for the given clientId. For example, after * this function is called, an entity is marked * dirty because it has changes to save. - * @param {onBlockUpdate} props.onInput Function to call when a non-persistent + * @param {onBlockUpdate} props.onInput Function to call when a non-persistent * change has been made in the block-editor blocks * for the given clientId. When this is called, * controlling sources do not become dirty. diff --git a/packages/block-editor/src/components/rich-text/index.js b/packages/block-editor/src/components/rich-text/index.js index 3629e6764d341..13d7e47bc5172 100644 --- a/packages/block-editor/src/components/rich-text/index.js +++ b/packages/block-editor/src/components/rich-text/index.js @@ -266,8 +266,8 @@ function RichTextWrapper( * blocks as a result of splitting the block by pasting block content in the * instance. * - * @param {Object} record The rich text value to split. - * @param {Array} pastedBlocks The pasted blocks to insert, if any. + * @param {Object} record The rich text value to split. + * @param {Array} pastedBlocks The pasted blocks to insert, if any. */ const splitValue = useCallback( ( record, pastedBlocks = [] ) => { diff --git a/packages/block-editor/src/components/unit-control/index.js b/packages/block-editor/src/components/unit-control/index.js index b6a37665a4f90..a4b3bed8149d2 100644 --- a/packages/block-editor/src/components/unit-control/index.js +++ b/packages/block-editor/src/components/unit-control/index.js @@ -14,7 +14,7 @@ export default function UnitControl( { units: unitsProp, ...props } ) { * Filters available units based on values defined by settings. * * @param {Array} settings Collection of preferred units. - * @param {Array} units Collection of available units. + * @param {Array} units Collection of available units. * * @return {Array} Filtered units based on settings. */ diff --git a/packages/block-editor/src/components/use-editor-feature/index.js b/packages/block-editor/src/components/use-editor-feature/index.js index b7bc591996274..394e64c4e44df 100644 --- a/packages/block-editor/src/components/use-editor-feature/index.js +++ b/packages/block-editor/src/components/use-editor-feature/index.js @@ -33,7 +33,7 @@ const deprecatedFlags = { * Hook that retrieves the setting for the given editor feature. * It works with nested objects using by finding the value at path. * - * @param {string} featurePath The path to the feature. + * @param {string} featurePath The path to the feature. * * @return {any} Returns the value defined for the setting. * diff --git a/packages/block-editor/src/components/use-moving-animation/index.js b/packages/block-editor/src/components/use-moving-animation/index.js index 41620e3649554..d9eced255174d 100644 --- a/packages/block-editor/src/components/use-moving-animation/index.js +++ b/packages/block-editor/src/components/use-moving-animation/index.js @@ -18,7 +18,7 @@ import { getScrollContainer } from '@wordpress/dom'; /** * Simple reducer used to increment a counter. * - * @param {number} state Previous counter value. + * @param {number} state Previous counter value. * @return {number} New state value. */ const counterReducer = ( state ) => state + 1; diff --git a/packages/block-editor/src/hooks/align.js b/packages/block-editor/src/hooks/align.js index f46b7fc029bc2..a5a9670a3fb2c 100644 --- a/packages/block-editor/src/hooks/align.js +++ b/packages/block-editor/src/hooks/align.js @@ -80,7 +80,7 @@ export function getValidAlignments( /** * Filters registered block settings, extending attributes to include `align`. * - * @param {Object} settings Original block settings + * @param {Object} settings Original block settings * @return {Object} Filtered block settings */ export function addAttribute( settings ) { @@ -115,7 +115,7 @@ export const AlignmentHookSettingsProvider = AlignmentHookSettings.Provider; * Override the default edit UI to include new toolbar controls for block * alignment, if block defines support. * - * @param {Function} BlockEdit Original component + * @param {Function} BlockEdit Original component * @return {Function} Wrapped component */ export const withToolbarControls = createHigherOrderComponent( @@ -166,7 +166,7 @@ export const withToolbarControls = createHigherOrderComponent( /** * Override the default block element to add alignment wrapper props. * - * @param {Function} BlockListBlock Original component + * @param {Function} BlockListBlock Original component * @return {Function} Wrapped component */ export const withDataAlign = createHigherOrderComponent( @@ -204,9 +204,9 @@ export const withDataAlign = createHigherOrderComponent( * Override props assigned to save component to inject alignment class name if * block supports it. * - * @param {Object} props Additional props applied to save element - * @param {Object} blockType Block type - * @param {Object} attributes Block attributes + * @param {Object} props Additional props applied to save element + * @param {Object} blockType Block type + * @param {Object} attributes Block attributes * @return {Object} Filtered props applied to save element */ export function addAssignedAlign( props, blockType, attributes ) { diff --git a/packages/block-editor/src/hooks/color.js b/packages/block-editor/src/hooks/color.js index c078c6c3a017d..a11b79475df94 100644 --- a/packages/block-editor/src/hooks/color.js +++ b/packages/block-editor/src/hooks/color.js @@ -60,7 +60,7 @@ const hasGradientSupport = ( blockType ) => { * Filters registered block settings, extending attributes to include * `backgroundColor` and `textColor` attribute. * - * @param {Object} settings Original block settings + * @param {Object} settings Original block settings * @return {Object} Filtered block settings */ function addAttributes( settings ) { @@ -98,9 +98,9 @@ function addAttributes( settings ) { /** * Override props assigned to save component to inject colors classnames. * - * @param {Object} props Additional props applied to save element - * @param {Object} blockType Block type - * @param {Object} attributes Block attributes + * @param {Object} props Additional props applied to save element + * @param {Object} blockType Block type + * @param {Object} attributes Block attributes * @return {Object} Filtered props applied to save element */ export function addSaveProps( props, blockType, attributes ) { @@ -145,7 +145,7 @@ export function addSaveProps( props, blockType, attributes ) { * Filters registered block settings to extand the block edit wrapper * to apply the desired styles and classnames properly. * - * @param {Object} settings Original block settings + * @param {Object} settings Original block settings * @return {Object} Filtered block settings */ export function addEditProps( settings ) { @@ -337,7 +337,7 @@ export function ColorEdit( props ) { * This adds inline styles for color palette colors. * Ideally, this is not needed and themes should load their palettes on the editor. * - * @param {Function} BlockListBlock Original component + * @param {Function} BlockListBlock Original component * @return {Function} Wrapped component */ export const withColorPaletteStyles = createHigherOrderComponent( diff --git a/packages/block-editor/src/hooks/font-size.js b/packages/block-editor/src/hooks/font-size.js index 08b3b6c4df32d..785dd8f29ffd8 100644 --- a/packages/block-editor/src/hooks/font-size.js +++ b/packages/block-editor/src/hooks/font-size.js @@ -24,7 +24,7 @@ export const FONT_SIZE_SUPPORT_KEY = '__experimentalFontSize'; * Filters registered block settings, extending attributes to include * `fontSize` and `fontWeight` attributes. * - * @param {Object} settings Original block settings + * @param {Object} settings Original block settings * @return {Object} Filtered block settings */ function addAttributes( settings ) { @@ -47,9 +47,9 @@ function addAttributes( settings ) { /** * Override props assigned to save component to inject font size. * - * @param {Object} props Additional props applied to save element - * @param {Object} blockType Block type - * @param {Object} attributes Block attributes + * @param {Object} props Additional props applied to save element + * @param {Object} blockType Block type + * @param {Object} attributes Block attributes * @return {Object} Filtered props applied to save element */ function addSaveProps( props, blockType, attributes ) { @@ -70,7 +70,7 @@ function addSaveProps( props, blockType, attributes ) { * Filters registered block settings to expand the block edit wrapper * by applying the desired styles and classnames. * - * @param {Object} settings Original block settings + * @param {Object} settings Original block settings * @return {Object} Filtered block settings */ function addEditProps( settings ) { @@ -160,7 +160,7 @@ export function useIsFontSizeDisabled( { name: blockName } = {} ) { * Ideally, this is not needed and themes load the font-size classes on the * editor. * - * @param {Function} BlockListBlock Original component + * @param {Function} BlockListBlock Original component * @return {Function} Wrapped component */ const withFontSizeInlineStyles = createHigherOrderComponent( diff --git a/packages/block-editor/src/hooks/style.js b/packages/block-editor/src/hooks/style.js index fe2f66a9c141c..42035e737224f 100644 --- a/packages/block-editor/src/hooks/style.js +++ b/packages/block-editor/src/hooks/style.js @@ -47,7 +47,7 @@ function compileStyleValue( uncompiledValue ) { /** * Returns the inline styles to add depending on the style object * - * @param {Object} styles Styles configuration + * @param {Object} styles Styles configuration * @return {Object} Flattened CSS variables declaration */ export function getInlineStyles( styles = {} ) { @@ -70,7 +70,7 @@ export function getInlineStyles( styles = {} ) { /** * Filters registered block settings, extending attributes to include `style` attribute. * - * @param {Object} settings Original block settings + * @param {Object} settings Original block settings * @return {Object} Filtered block settings */ function addAttribute( settings ) { @@ -93,9 +93,9 @@ function addAttribute( settings ) { /** * Override props assigned to save component to inject the CSS variables definition. * - * @param {Object} props Additional props applied to save element - * @param {Object} blockType Block type - * @param {Object} attributes Block attributes + * @param {Object} props Additional props applied to save element + * @param {Object} blockType Block type + * @param {Object} attributes Block attributes * @return {Object} Filtered props applied to save element */ export function addSaveProps( props, blockType, attributes ) { @@ -116,7 +116,7 @@ export function addSaveProps( props, blockType, attributes ) { * Filters registered block settings to extand the block edit wrapper * to apply the desired styles and classnames properly. * - * @param {Object} settings Original block settings + * @param {Object} settings Original block settings * @return {Object} Filtered block settings */ export function addEditProps( settings ) { @@ -141,7 +141,7 @@ export function addEditProps( settings ) { * Override the default edit UI to include new inspector controls for * all the custom styles configs. * - * @param {Function} BlockEdit Original component + * @param {Function} BlockEdit Original component * @return {Function} Wrapped component */ export const withBlockControls = createHigherOrderComponent( diff --git a/packages/block-editor/src/store/actions.js b/packages/block-editor/src/store/actions.js index 963ce993aae83..5645e0f869360 100644 --- a/packages/block-editor/src/store/actions.js +++ b/packages/block-editor/src/store/actions.js @@ -287,9 +287,9 @@ function getBlocksWithDefaultStylesApplied( blocks, blockEditorSettings ) { * Returns an action object signalling that a blocks should be replaced with * one or more replacement blocks. * - * @param {(string|string[])} clientIds Block client ID(s) to replace. - * @param {(Object|Object[])} blocks Replacement block(s). - * @param {number} indexToSelect Index of replacement block to select. + * @param {(string|string[])} clientIds Block client ID(s) to replace. + * @param {(Object|Object[])} blocks Replacement block(s). + * @param {number} indexToSelect Index of replacement block to select. * @param {number} initialPosition Index of caret after in the selected block after the operation. * * @yield {Object} Action object. @@ -372,10 +372,10 @@ export const moveBlocksUp = createOnMove( 'MOVE_BLOCKS_UP' ); * Returns an action object signalling that the given blocks should be moved to * a new position. * - * @param {?string} clientIds The client IDs of the blocks. - * @param {?string} fromRootClientId Root client ID source. - * @param {?string} toRootClientId Root client ID destination. - * @param {number} index The index to move the blocks to. + * @param {?string} clientIds The client IDs of the blocks. + * @param {?string} fromRootClientId Root client ID source. + * @param {?string} toRootClientId Root client ID destination. + * @param {number} index The index to move the blocks to. * * @yield {Object} Action object. */ @@ -435,10 +435,10 @@ export function* moveBlocksToPosition( * Returns an action object signalling that the given block should be moved to a * new position. * - * @param {?string} clientId The client ID of the block. - * @param {?string} fromRootClientId Root client ID source. - * @param {?string} toRootClientId Root client ID destination. - * @param {number} index The index to move the block to. + * @param {?string} clientId The client ID of the block. + * @param {?string} fromRootClientId Root client ID source. + * @param {?string} toRootClientId Root client ID destination. + * @param {number} index The index to move the block to. * * @yield {Object} Action object. */ @@ -460,9 +460,9 @@ export function* moveBlockToPosition( * Returns an action object used in signalling that a single block should be * inserted, optionally at a specific index respective a root block list. * - * @param {Object} block Block object to insert. - * @param {?number} index Index at which block should be inserted. - * @param {?string} rootClientId Optional root client ID of block list on which to insert. + * @param {Object} block Block object to insert. + * @param {?number} index Index at which block should be inserted. + * @param {?string} rootClientId Optional root client ID of block list on which to insert. * @param {?boolean} updateSelection If true block selection will be updated. If false, block selection will not change. Defaults to true. * * @return {Object} Action object. @@ -553,7 +553,7 @@ export function hideInsertionPoint() { /** * Returns an action object resetting the template validity. * - * @param {boolean} isValid template validity flag. + * @param {boolean} isValid template validity flag. * * @return {Object} Action object. */ @@ -941,7 +941,7 @@ export function* setBlockMovingClientId( hasBlockMovingClientId = null ) { * Generator that triggers an action used to duplicate a list of blocks. * * @param {string[]} clientIds - * @param {boolean} updateSelection + * @param {boolean} updateSelection */ export function* duplicateBlocks( clientIds, updateSelection = true ) { if ( ! clientIds && ! clientIds.length ) { @@ -1061,7 +1061,7 @@ export function* insertAfterBlock( clientId ) { /** * Returns an action object that toggles the highlighted block state. * - * @param {string} clientId The block's clientId. + * @param {string} clientId The block's clientId. * @param {boolean} isHighlighted The highlight state. */ export function toggleBlockHighlight( clientId, isHighlighted ) { @@ -1090,7 +1090,7 @@ export function* flashBlock( clientId ) { /** * Returns an action object that sets whether the block has controlled innerblocks. * - * @param {string} clientId The block's clientId. + * @param {string} clientId The block's clientId. * @param {boolean} hasControlledInnerBlocks True if the block's inner blocks are controlled. */ export function setHasControlledInnerBlocks( diff --git a/packages/block-editor/src/store/controls.js b/packages/block-editor/src/store/controls.js index f0cbed509f313..97b88ea2821a0 100644 --- a/packages/block-editor/src/store/controls.js +++ b/packages/block-editor/src/store/controls.js @@ -8,7 +8,7 @@ import { createRegistryControl } from '@wordpress/data'; * * @param {string} storeName Store name. * @param {string} selectorName Selector name. - * @param {Array} args Selector arguments. + * @param {Array} args Selector arguments. * * @return {Object} control descriptor. */ diff --git a/packages/block-editor/src/store/defaults.js b/packages/block-editor/src/store/defaults.js index 7d5ae73011342..2a1a8d82c1c01 100644 --- a/packages/block-editor/src/store/defaults.js +++ b/packages/block-editor/src/store/defaults.js @@ -11,29 +11,29 @@ export const PREFERENCES_DEFAULTS = { * The default editor settings * * @typedef {Object} SETTINGS_DEFAULT - * @property {boolean} alignWide Enable/Disable Wide/Full Alignments - * @property {Array} availableLegacyWidgets Array of objects representing the legacy widgets available. - * @property {Array} colors Palette colors - * @property {Array} fontSizes Available font sizes - * @property {boolean} imageEditing Image Editing settings set to false to disable. - * @property {Array} imageSizes Available image sizes - * @property {number} maxWidth Max width to constraint resizing - * @property {boolean|Array} allowedBlockTypes Allowed block types - * @property {boolean} hasFixedToolbar Whether or not the editor toolbar is fixed - * @property {boolean} hasPermissionsToManageWidgets Whether or not the user is able to manage widgets. - * @property {boolean} focusMode Whether the focus mode is enabled or not - * @property {Array} styles Editor Styles - * @property {boolean} isRTL Whether the editor is in RTL mode - * @property {boolean} keepCaretInsideBlock Whether caret should move between blocks in edit mode - * @property {string} bodyPlaceholder Empty post placeholder - * @property {string} titlePlaceholder Empty title placeholder - * @property {boolean} codeEditingEnabled Whether or not the user can switch to the code editor - * @property {boolean} __experimentalCanUserUseUnfilteredHTML Whether the user should be able to use unfiltered HTML or the HTML should be filtered e.g., to remove elements considered insecure like iframes. - * @property {boolean} __experimentalBlockDirectory Whether the user has enabled the Block Directory - * @property {boolean} __experimentalEnableFullSiteEditing Whether the user has enabled Full Site Editing - * @property {boolean} __experimentalEnableFullSiteEditingDemo Whether the user has enabled Full Site Editing Demo Templates - * @property {Array} __experimentalBlockPatterns Array of objects representing the block patterns - * @property {Array} __experimentalBlockPatternCategories Array of objects representing the block pattern categories + * @property {boolean} alignWide Enable/Disable Wide/Full Alignments + * @property {Array} availableLegacyWidgets Array of objects representing the legacy widgets available. + * @property {Array} colors Palette colors + * @property {Array} fontSizes Available font sizes + * @property {boolean} imageEditing Image Editing settings set to false to disable. + * @property {Array} imageSizes Available image sizes + * @property {number} maxWidth Max width to constraint resizing + * @property {boolean|Array} allowedBlockTypes Allowed block types + * @property {boolean} hasFixedToolbar Whether or not the editor toolbar is fixed + * @property {boolean} hasPermissionsToManageWidgets Whether or not the user is able to manage widgets. + * @property {boolean} focusMode Whether the focus mode is enabled or not + * @property {Array} styles Editor Styles + * @property {boolean} isRTL Whether the editor is in RTL mode + * @property {boolean} keepCaretInsideBlock Whether caret should move between blocks in edit mode + * @property {string} bodyPlaceholder Empty post placeholder + * @property {string} titlePlaceholder Empty title placeholder + * @property {boolean} codeEditingEnabled Whether or not the user can switch to the code editor + * @property {boolean} __experimentalCanUserUseUnfilteredHTML Whether the user should be able to use unfiltered HTML or the HTML should be filtered e.g., to remove elements considered insecure like iframes. + * @property {boolean} __experimentalBlockDirectory Whether the user has enabled the Block Directory + * @property {boolean} __experimentalEnableFullSiteEditing Whether the user has enabled Full Site Editing + * @property {boolean} __experimentalEnableFullSiteEditingDemo Whether the user has enabled Full Site Editing Demo Templates + * @property {Array} __experimentalBlockPatterns Array of objects representing the block patterns + * @property {Array} __experimentalBlockPatternCategories Array of objects representing the block pattern categories */ export const SETTINGS_DEFAULTS = { alignWide: false, diff --git a/packages/block-editor/src/store/reducer.js b/packages/block-editor/src/store/reducer.js index 058f0794ab2d1..914a86c3fd8ae 100644 --- a/packages/block-editor/src/store/reducer.js +++ b/packages/block-editor/src/store/reducer.js @@ -80,7 +80,7 @@ function mapBlockParents( blocks, rootClientId = '' ) { * applying a transformation function to each one. * Returns a flattened object with the transformed blocks. * - * @param {Array} blocks Blocks to flatten. + * @param {Array} blocks Blocks to flatten. * @param {Function} transform Transforming function to be applied to each block. * * @return {Object} Flattened object. @@ -138,9 +138,9 @@ function getFlattenedBlockAttributes( blocks ) { * an inner block controller. To do so, it must be excluded from the list of * client IDs which are considered to be part of the top-level entity. * - * @param {Object} blocksOrder Object that maps block client IDs to a list of + * @param {Object} blocksOrder Object that maps block client IDs to a list of * nested block client IDs. - * @param {?string} rootClientId The root client ID to search. Defaults to ''. + * @param {?string} rootClientId The root client ID to search. Defaults to ''. * @param {?Object} controlledInnerBlocks The InnerBlocks controller state. * * @return {Array} List of descendant client IDs. @@ -1134,7 +1134,7 @@ export function isTyping( state = false, action ) { * Reducer returning dragged block client id. * * @param {string[]} state Current state. - * @param {Object} action Dispatched action. + * @param {Object} action Dispatched action. * * @return {string[]} Updated state. */ @@ -1438,8 +1438,8 @@ export function settings( state = SETTINGS_DEFAULTS, action ) { /** * Reducer returning the user preferences. * - * @param {Object} state Current state. - * @param {Object} action Dispatched action. + * @param {Object} state Current state. + * @param {Object} action Dispatched action. * * @return {string} Updated state. */ @@ -1539,7 +1539,7 @@ export function isNavigationMode( state = false, action ) { * Reducer returning whether the block moving mode is enabled or not. * * @param {string|null} state Current state. - * @param {Object} action Dispatched action. + * @param {Object} action Dispatched action. * * @return {string|null} Updated state. */ diff --git a/packages/block-editor/src/store/selectors.js b/packages/block-editor/src/store/selectors.js index 85c4a17d94bd4..a4ae06d90a433 100644 --- a/packages/block-editor/src/store/selectors.js +++ b/packages/block-editor/src/store/selectors.js @@ -266,8 +266,8 @@ export const __unstableGetBlockTree = createSelector( * Returns an array containing the clientIds of all descendants * of the blocks given. * - * @param {Object} state Global application state. - * @param {Array} clientIds Array of blocks to inspect. + * @param {Object} state Global application state. + * @param {Array} clientIds Array of blocks to inspect. * * @return {Array} ids of descendants. */ @@ -492,8 +492,8 @@ export function getBlockRootClientId( state, clientId ) { /** * Given a block client ID, returns the list of all its parents from top to bottom. * - * @param {Object} state Editor state. - * @param {string} clientId Block from which to find root client ID. + * @param {Object} state Editor state. + * @param {string} clientId Block from which to find root client ID. * @param {boolean} ascending Order results from bottom to top (true) or top to bottom (false). * * @return {Array} ClientIDs of the parent blocks. @@ -517,9 +517,9 @@ export const getBlockParents = createSelector( * returns the list of all its parents from top to bottom, * filtered by the given name. * - * @param {Object} state Editor state. - * @param {string} clientId Block from which to find root client ID. - * @param {string} blockName Block name to filter. + * @param {Object} state Editor state. + * @param {string} clientId Block from which to find root client ID. + * @param {string} blockName Block name to filter. * @param {boolean} ascending Order results from bottom to top (true) or top to bottom (false). * * @return {Array} ClientIDs of the parent blocks. @@ -1351,8 +1351,8 @@ function getInsertUsage( state, id ) { /** * Returns whether we can show a block type in the inserter * - * @param {Object} state Global State - * @param {Object} blockType BlockType + * @param {Object} state Global State + * @param {Object} blockType BlockType * @param {?string} rootClientId Optional root client ID of block list. * * @return {boolean} Whether the given block type is allowed to be shown in the inserter. @@ -1659,8 +1659,8 @@ export function isLastBlockChangePersistent( state ) { /** * Returns the Block List settings for an array of blocks, if any exist. * - * @param {Object} state Editor state. - * @param {Array} clientIds Block client IDs. + * @param {Object} state Editor state. + * @param {Array} clientIds Block client IDs. * * @return {Array} Block List Settings for each of the found blocks */ @@ -1778,7 +1778,7 @@ export function didAutomaticChange( state ) { /** * Returns true if the current highlighted block matches the block clientId. * - * @param {Object} state Global application state. + * @param {Object} state Global application state. * @param {string} clientId The block to check. * * @return {boolean} Whether the block is currently highlighted. @@ -1790,7 +1790,7 @@ export function isBlockHighlighted( state, clientId ) { /** * Checks if a given block has controlled inner blocks. * - * @param {Object} state Global application state. + * @param {Object} state Global application state. * @param {string} clientId The block to check. * * @return {boolean} True if the block has controlled inner blocks. diff --git a/packages/block-editor/src/utils/transform-styles/index.js b/packages/block-editor/src/utils/transform-styles/index.js index b0f1d66fe5511..854ffd11da2ce 100644 --- a/packages/block-editor/src/utils/transform-styles/index.js +++ b/packages/block-editor/src/utils/transform-styles/index.js @@ -18,7 +18,7 @@ import wrap from './transforms/wrap'; /** * Applies a series of CSS rule transforms to wrap selectors inside a given class and/or rewrite URLs depending on the parameters passed. * - * @param {Array} styles CSS rules. + * @param {Array} styles CSS rules. * @param {string} wrapperClassName Wrapper Class Name. * @return {Array} converted rules. */ diff --git a/packages/block-editor/src/utils/transform-styles/transforms/url-rewrite.js b/packages/block-editor/src/utils/transform-styles/transforms/url-rewrite.js index a33917b44afdb..ad623dcf33530 100644 --- a/packages/block-editor/src/utils/transform-styles/transforms/url-rewrite.js +++ b/packages/block-editor/src/utils/transform-styles/transforms/url-rewrite.js @@ -1,7 +1,7 @@ /** * Return `true` if the given path is http/https. * - * @param {string} filePath path + * @param {string} filePath path * * @return {boolean} is remote path. */ @@ -12,7 +12,7 @@ function isRemotePath( filePath ) { /** * Return `true` if the given filePath is an absolute url. * - * @param {string} filePath path + * @param {string} filePath path * * @return {boolean} is absolute path. */ @@ -23,7 +23,7 @@ function isAbsolutePath( filePath ) { /** * Whether or not the url should be inluded. * - * @param {Object} meta url meta info + * @param {Object} meta url meta info * * @return {boolean} is valid. */ @@ -51,8 +51,8 @@ function isValidURL( meta ) { /** * Get the absolute path of the url, relative to the basePath * - * @param {string} str the url - * @param {string} baseURL base URL + * @param {string} str the url + * @param {string} baseURL base URL * * @return {string} the full path to the file */ @@ -63,7 +63,7 @@ function getResourcePath( str, baseURL ) { /** * Process the single `url()` pattern * - * @param {string} baseURL the base URL for relative URLs + * @param {string} baseURL the base URL for relative URLs * @return {Promise} the Promise */ function processURL( baseURL ) { @@ -83,7 +83,7 @@ function processURL( baseURL ) { /** * Get all `url()`s, and return the meta info * - * @param {string} value decl.value + * @param {string} value decl.value * * @return {Array} the urls */ @@ -110,8 +110,8 @@ function getURLs( value ) { /** * Replace the raw value's `url()` segment to the new value * - * @param {string} raw the raw value - * @param {Array} URLs the URLs to replace + * @param {string} raw the raw value + * @param {Array} URLs the URLs to replace * * @return {string} the new value */ diff --git a/packages/block-library/src/code/utils.js b/packages/block-library/src/code/utils.js index 30609b1f0ee74..b304a592e580c 100644 --- a/packages/block-library/src/code/utils.js +++ b/packages/block-library/src/code/utils.js @@ -30,7 +30,7 @@ export function escape( content ) { * This function replicates the escaping of HTML tags, where a tag like * becomes <strong>. * - * @param {string} content The content of a code block. + * @param {string} content The content of a code block. * @return {string} The given content with its opening shortcode characters * converted into their HTML entity counterpart * (i.e. [ => [) @@ -49,7 +49,7 @@ function escapeOpeningSquareBrackets( content ) { * * See https://github.com/WordPress/wordpress-develop/blob/5.1.1/src/wp-includes/class-wp-embed.php#L403 * - * @param {string} content The content of a code block. + * @param {string} content The content of a code block. * @return {string} The given content with its ampersands converted into * their HTML entity counterpart (i.e. & => &) */ diff --git a/packages/block-library/src/embed/util.js b/packages/block-library/src/embed/util.js index 172ab152d89cc..2a9db6112a4b5 100644 --- a/packages/block-library/src/embed/util.js +++ b/packages/block-library/src/embed/util.js @@ -43,8 +43,8 @@ export const getEmbedInfoByProvider = ( provider ) => /** * Returns true if any of the regular expressions match the URL. * - * @param {string} url The URL to test. - * @param {Array} patterns The list of regular expressions to test agains. + * @param {string} url The URL to test. + * @param {Array} patterns The list of regular expressions to test agains. * @return {boolean} True if any of the regular expressions match the URL. */ export const matchesPatterns = ( url, patterns = [] ) => @@ -54,7 +54,7 @@ export const matchesPatterns = ( url, patterns = [] ) => * Finds the block variation that should be used for the URL, * based on the provided URL and the variation's patterns. * - * @param {string} url The URL to test. + * @param {string} url The URL to test. * @return {WPBlockVariation} The block variation that should be used for this URL */ export const findMoreSuitableBlock = ( url ) => @@ -87,8 +87,8 @@ export const getPhotoHtml = ( photo ) => { * versions, so we require that these are generated separately. * See `getAttributesFromPreview` in the generated embed edit component. * - * @param {Object} props The block's props. - * @param {Object} [attributesFromPreview] Attributes generated from the block's most up to date preview. + * @param {Object} props The block's props. + * @param {Object} [attributesFromPreview] Attributes generated from the block's most up to date preview. * @return {Object|undefined} A more suitable embed block if one exists. */ export const createUpgradedEmbedBlock = ( diff --git a/packages/block-library/src/image/edit.js b/packages/block-library/src/image/edit.js index 54246499701a9..864160b8e84af 100644 --- a/packages/block-library/src/image/edit.js +++ b/packages/block-library/src/image/edit.js @@ -49,7 +49,7 @@ export const pickRelevantMediaFiles = ( image ) => { * Is the URL a temporary blob URL? A blob URL is one that is used temporarily * while the image is being uploaded and will not have an id yet allocated. * - * @param {number=} id The id of the image. + * @param {number=} id The id of the image. * @param {string=} url The url of the image. * * @return {boolean} Is the URL a Blob URL diff --git a/packages/block-library/src/image/utils.js b/packages/block-library/src/image/utils.js index 8891d862cb55c..0f6a1ec38ad4a 100644 --- a/packages/block-library/src/image/utils.js +++ b/packages/block-library/src/image/utils.js @@ -35,9 +35,9 @@ export function removeNewTabRel( currentRel ) { /** * Helper to get the link target settings to be stored. * - * @param {boolean} value The new link target value. - * @param {Object} attributes Block attributes. - * @param {Object} attributes.rel Image block's rel attribute. + * @param {boolean} value The new link target value. + * @param {Object} attributes Block attributes. + * @param {Object} attributes.rel Image block's rel attribute. * * @return {Object} Updated link target settings. */ diff --git a/packages/block-library/src/navigation/create-data-tree.js b/packages/block-library/src/navigation/create-data-tree.js index 255c5a7b18da7..f782b6b9370b0 100644 --- a/packages/block-library/src/navigation/create-data-tree.js +++ b/packages/block-library/src/navigation/create-data-tree.js @@ -8,9 +8,9 @@ * * This is useful for building linked lists of data from flat data structures. * - * @param {Array} dataset linked data to be rearranged into a hierarchical tree based on relational fields. - * @param {string} id the property which uniquely identifies each entry within the array. - * @param {*} relation the property which identifies how the current item is related to other items in the data (if at all). + * @param {Array} dataset linked data to be rearranged into a hierarchical tree based on relational fields. + * @param {string} id the property which uniquely identifies each entry within the array. + * @param {*} relation the property which identifies how the current item is related to other items in the data (if at all). * @return {Array} a nested array of parent/child relationships */ function createDataTree( dataset, id = 'id', relation = 'parent' ) { diff --git a/packages/block-library/src/query/utils.js b/packages/block-library/src/query/utils.js index 2e55a6b9365ce..fcf6f9074d6aa 100644 --- a/packages/block-library/src/query/utils.js +++ b/packages/block-library/src/query/utils.js @@ -4,15 +4,15 @@ * Tags ref: https://developer.wordpress.org/rest-api/reference/tags/ * * @typedef {Object} WPTerm - * @property {number} id Unique identifier for the term. - * @property {number} count Number of published posts for the term. + * @property {number} id Unique identifier for the term. + * @property {number} count Number of published posts for the term. * @property {string} description HTML description of the term. - * @property {string} link URL of the term. - * @property {string} name HTML title for the term. - * @property {string} slug An alphanumeric identifier for the term unique to its type. - * @property {string} taxonomy Type attribution for the term. - * @property {Object} meta Meta fields - * @property {number} [parent] The parent term ID. + * @property {string} link URL of the term. + * @property {string} name HTML title for the term. + * @property {string} slug An alphanumeric identifier for the term unique to its type. + * @property {string} taxonomy Type attribution for the term. + * @property {Object} meta Meta fields + * @property {number} [parent] The parent term ID. */ /** @@ -20,10 +20,10 @@ * from an array of WPTerm. * * @typedef {Object} QueryTermsInfo - * @property {WPTerm[]} terms The array of terms. + * @property {WPTerm[]} terms The array of terms. * @property {Object} mapById Object mapping with the term id as key and the term as value. * @property {Object} mapByName Object mapping with the term name as key and the term as value. - * @property {string[]} names Array with the terms' names. + * @property {string[]} names Array with the terms' names. */ /** diff --git a/packages/block-library/src/table/state.js b/packages/block-library/src/table/state.js index 2080bf28105d2..594578ce8ae6e 100644 --- a/packages/block-library/src/table/state.js +++ b/packages/block-library/src/table/state.js @@ -47,7 +47,7 @@ export function getFirstRow( state ) { /** * Gets an attribute for a cell. * - * @param {Object} state Current table state. + * @param {Object} state Current table state. * @param {Object} cellLocation The location of the cell * @param {string} attributeName The name of the attribute to get the value of. * diff --git a/packages/blocks/src/api/factory.js b/packages/blocks/src/api/factory.js index d87d16cafd026..75c672d415f82 100644 --- a/packages/blocks/src/api/factory.js +++ b/packages/blocks/src/api/factory.js @@ -95,9 +95,9 @@ export function createBlock( name, attributes = {}, innerBlocks = [] ) { * Given a block object, returns a copy of the block object, optionally merging * new attributes and/or replacing its inner blocks. * - * @param {Object} block Block instance. - * @param {Object} mergeAttributes Block attributes. - * @param {?Array} newInnerBlocks Nested blocks. + * @param {Object} block Block instance. + * @param {Object} mergeAttributes Block attributes. + * @param {?Array} newInnerBlocks Nested blocks. * * @return {Object} A cloned block. */ @@ -123,7 +123,7 @@ export function cloneBlock( block, mergeAttributes = {}, newInnerBlocks ) { * * @param {Object} transform The transform object to validate. * @param {string} direction Is this a 'from' or 'to' transform. - * @param {Array} blocks The blocks to transform from. + * @param {Array} blocks The blocks to transform from. * * @return {boolean} Is the transform possible? */ @@ -197,7 +197,7 @@ const isPossibleTransformForSource = ( transform, direction, blocks ) => { * Returns block types that the 'blocks' can be transformed into, based on * 'from' transforms on other blocks. * - * @param {Array} blocks The blocks to transform from. + * @param {Array} blocks The blocks to transform from. * * @return {Array} Block types that the blocks can be transformed into. */ @@ -281,7 +281,7 @@ export const isWildcardBlockTransform = ( t ) => * acts as a container Block for other Blocks as part of the * Grouping mechanics * - * @param {string} name the name of the Block to test against + * @param {string} name the name of the Block to test against * * @return {boolean} whether or not the Block is the container Block type */ @@ -353,8 +353,8 @@ export function findTransform( transforms, predicate ) { * If no block name is provided, returns transforms for all blocks. A normal * transform object includes `blockName` as a property. * - * @param {string} direction Transform direction ("to", "from"). - * @param {string|Object} blockTypeOrName Block type or name. + * @param {string} direction Transform direction ("to", "from"). + * @param {string|Object} blockTypeOrName Block type or name. * * @return {Array} Block transforms for direction. */ diff --git a/packages/blocks/src/api/node.js b/packages/blocks/src/api/node.js index ad749132863de..796442a1936ce 100644 --- a/packages/blocks/src/api/node.js +++ b/packages/blocks/src/api/node.js @@ -24,7 +24,7 @@ const { TEXT_NODE, ELEMENT_NODE } = window.Node; * corresponds to that type, false otherwise. * * @param {WPBlockNode} node Block node to test - * @param {string} type Node to type to test against. + * @param {string} type Node to type to test against. * * @return {boolean} Whether node is of intended type. */ diff --git a/packages/blocks/src/api/parser.js b/packages/blocks/src/api/parser.js index 41c5da75dddf7..48d3981506261 100644 --- a/packages/blocks/src/api/parser.js +++ b/packages/blocks/src/api/parser.js @@ -211,8 +211,8 @@ export function matcherFromSource( sourceConfig ) { * Given a block's raw content and an attribute's schema returns the attribute's * value depending on its source. * - * @param {string} innerHTML Block's raw content. - * @param {Object} attributeSchema Attribute's schema. + * @param {string} innerHTML Block's raw content. + * @param {Object} attributeSchema Attribute's schema. * * @return {*} Attribute value. */ diff --git a/packages/blocks/src/api/raw-handling/index.js b/packages/blocks/src/api/raw-handling/index.js index f0e51d23dbb80..05888de363ae7 100644 --- a/packages/blocks/src/api/raw-handling/index.js +++ b/packages/blocks/src/api/raw-handling/index.js @@ -51,9 +51,9 @@ function getRawTransformations() { * top-level tag. The HTML should be filtered to not have any text between * top-level tags and formatted in a way that blocks can handle the HTML. * - * @param {Object} $1 Named parameters. - * @param {string} $1.html HTML to convert. - * @param {Array} $1.rawTransforms Transforms that can be used. + * @param {Object} $1 Named parameters. + * @param {string} $1.html HTML to convert. + * @param {Array} $1.rawTransforms Transforms that can be used. * * @return {Array} An array of blocks. */ diff --git a/packages/blocks/src/api/raw-handling/paste-handler.js b/packages/blocks/src/api/raw-handling/paste-handler.js index 6877b9fbb9279..33995a4f6fc47 100644 --- a/packages/blocks/src/api/raw-handling/paste-handler.js +++ b/packages/blocks/src/api/raw-handling/paste-handler.js @@ -84,9 +84,9 @@ function getRawTransformations() { * top-level tag. The HTML should be filtered to not have any text between * top-level tags and formatted in a way that blocks can handle the HTML. * - * @param {Object} $1 Named parameters. - * @param {string} $1.html HTML to convert. - * @param {Array} $1.rawTransforms Transforms that can be used. + * @param {Object} $1 Named parameters. + * @param {string} $1.html HTML to convert. + * @param {Array} $1.rawTransforms Transforms that can be used. * * @return {Array} An array of blocks. */ @@ -124,14 +124,14 @@ function htmlToBlocks( { html, rawTransforms } ) { /** * Converts an HTML string to known blocks. Strips everything else. * - * @param {Object} options - * @param {string} [options.HTML] The HTML to convert. - * @param {string} [options.plainText] Plain text version. - * @param {string} [options.mode] Handle content as blocks or inline content. + * @param {Object} options + * @param {string} [options.HTML] The HTML to convert. + * @param {string} [options.plainText] Plain text version. + * @param {string} [options.mode] Handle content as blocks or inline content. * * 'AUTO': Decide based on the content passed. * * 'INLINE': Always handle as inline content, and return string. * * 'BLOCKS': Always handle as blocks, and return array of blocks. - * @param {Array} [options.tagName] The tag into which content will be inserted. + * @param {Array} [options.tagName] The tag into which content will be inserted. * * @return {Array|string} A list of blocks or a string, depending on `handlerMode`. */ diff --git a/packages/blocks/src/api/registration.js b/packages/blocks/src/api/registration.js index 9052c76faf694..58a3c4500f796 100644 --- a/packages/blocks/src/api/registration.js +++ b/packages/blocks/src/api/registration.js @@ -78,22 +78,22 @@ import { DEPRECATED_ENTRY_KEYS } from './constants'; * * @typedef {Object} WPBlockVariation * - * @property {string} name The unique and machine-readable name. - * @property {string} title A human-readable variation title. - * @property {string} [description] A detailed variation description. - * @property {WPIcon} [icon] An icon helping to visualize the variation. - * @property {boolean} [isDefault] Indicates whether the current variation is + * @property {string} name The unique and machine-readable name. + * @property {string} title A human-readable variation title. + * @property {string} [description] A detailed variation description. + * @property {WPIcon} [icon] An icon helping to visualize the variation. + * @property {boolean} [isDefault] Indicates whether the current variation is * the default one. Defaults to `false`. - * @property {Object} [attributes] Values which override block attributes. - * @property {Array[]} [innerBlocks] Initial configuration of nested blocks. - * @property {Object} [example] Example provides structured data for + * @property {Object} [attributes] Values which override block attributes. + * @property {Array[]} [innerBlocks] Initial configuration of nested blocks. + * @property {Object} [example] Example provides structured data for * the block preview. You can set to * `undefined` to disable the preview shown * for the block type. - * @property {WPBlockVariationScope[]} [scope] The list of scopes where the variation + * @property {WPBlockVariationScope[]} [scope] The list of scopes where the variation * is applicable. When not provided, it * assumes all available scopes. - * @property {string[]} [keywords] An array of terms (which can be translated) + * @property {string[]} [keywords] An array of terms (which can be translated) * that help users discover the variation * while searching. */ @@ -416,9 +416,9 @@ export function getBlockTypes() { /** * Returns the block support value for a feature, if defined. * - * @param {(string|Object)} nameOrType Block name or type object - * @param {string} feature Feature to retrieve - * @param {*} defaultSupports Default value to return if not + * @param {(string|Object)} nameOrType Block name or type object + * @param {string} feature Feature to retrieve + * @param {*} defaultSupports Default value to return if not * explicitly defined * * @return {?*} Block support value diff --git a/packages/blocks/src/api/serializer.js b/packages/blocks/src/api/serializer.js index 886a1ad69b613..ca85c7df7883e 100644 --- a/packages/blocks/src/api/serializer.js +++ b/packages/blocks/src/api/serializer.js @@ -72,9 +72,9 @@ export function getBlockMenuDefaultClassName( blockName ) { * Given a block type containing a save render implementation and attributes, returns the * enhanced element to be saved or string when raw HTML expected. * - * @param {string|Object} blockTypeOrName Block type or name. - * @param {Object} attributes Block attributes. - * @param {?Array} innerBlocks Nested blocks. + * @param {string|Object} blockTypeOrName Block type or name. + * @param {Object} attributes Block attributes. + * @param {?Array} innerBlocks Nested blocks. * * @return {Object|string} Save element or raw HTML string. */ @@ -169,7 +169,7 @@ export function getSaveContent( blockTypeOrName, attributes, innerBlocks ) { * This function returns only those attributes which are needed to persist and * which cannot be matched from the block content. * - * @param {Object} blockType Block type. + * @param {Object} blockType Block type. * @param {Object} attributes Attributes from in-memory block data. * * @return {Object} Subset of attributes for comment serialization. diff --git a/packages/blocks/src/api/templates.js b/packages/blocks/src/api/templates.js index 5d21e0bf5a592..7ad1c5612c249 100644 --- a/packages/blocks/src/api/templates.js +++ b/packages/blocks/src/api/templates.js @@ -17,8 +17,8 @@ import { getBlockType } from './registration'; /** * Checks whether a list of blocks matches a template by comparing the block names. * - * @param {Array} blocks Block list. - * @param {Array} template Block template. + * @param {Array} blocks Block list. + * @param {Array} template Block template. * * @return {boolean} Whether the list of blocks matches a templates */ @@ -43,8 +43,8 @@ export function doBlocksMatchTemplate( blocks = [], template = [] ) { * (If it has the same name) and if doesn't match, we create a new block based on the template. * Extra blocks not present in the template are removed. * - * @param {Array} blocks Block list. - * @param {Array} template Block template. + * @param {Array} blocks Block list. + * @param {Array} template Block template. * * @return {Array} Updated Block list. */ diff --git a/packages/blocks/src/api/utils.js b/packages/blocks/src/api/utils.js index dbf1dc79049b9..00569989dad47 100644 --- a/packages/blocks/src/api/utils.js +++ b/packages/blocks/src/api/utils.js @@ -30,7 +30,7 @@ const ICON_COLORS = [ '#191e23', '#f8f9f9' ]; * and its attributes are equal to the default attributes * which means the block is unmodified. * - * @param {WPBlock} block Block Object + * @param {WPBlock} block Block Object * * @return {boolean} Whether the block is an unmodified default block */ @@ -62,7 +62,7 @@ export function isUnmodifiedDefaultBlock( block ) { /** * Function that checks if the parameter is a valid icon. * - * @param {*} icon Parameter to be checked. + * @param {*} icon Parameter to be checked. * * @return {boolean} True if the parameter is a valid icon and false otherwise. */ @@ -117,7 +117,7 @@ export function normalizeIconObject( icon ) { * it converts it to the matching block type object. * It passes the original object otherwise. * - * @param {string|Object} blockTypeOrName Block type or name. + * @param {string|Object} blockTypeOrName Block type or name. * * @return {?Object} Block type. */ diff --git a/packages/blocks/src/api/validation/index.js b/packages/blocks/src/api/validation/index.js index b31cf4e4e4536..e8a011ce60fc6 100644 --- a/packages/blocks/src/api/validation/index.js +++ b/packages/blocks/src/api/validation/index.js @@ -540,8 +540,8 @@ function getHTMLTokens( html, logger = createLogger() ) { /** * Returns true if the next HTML token closes the current token. * - * @param {Object} currentToken Current token to compare with. - * @param {Object|undefined} nextToken Next token to compare against. + * @param {Object} currentToken Current token to compare with. + * @param {Object|undefined} nextToken Next token to compare against. * * @return {boolean} true if `nextToken` closes `currentToken`, false otherwise */ diff --git a/packages/blocks/src/store/actions.js b/packages/blocks/src/store/actions.js index 6339db222cf22..ff24ac6b1a414 100644 --- a/packages/blocks/src/store/actions.js +++ b/packages/blocks/src/store/actions.js @@ -36,8 +36,8 @@ export function removeBlockTypes( names ) { /** * Returns an action object used in signalling that new block styles have been added. * - * @param {string} blockName Block name. - * @param {Array|Object} styles Block styles. + * @param {string} blockName Block name. + * @param {Array|Object} styles Block styles. * * @return {Object} Action object. */ @@ -190,9 +190,9 @@ export function updateCategory( slug, category ) { /** * Returns an action object used to add block collections * - * @param {string} namespace The namespace of the blocks to put in the collection - * @param {string} title The title to display in the block inserter - * @param {Object} icon (optional) The icon to display in the block inserter + * @param {string} namespace The namespace of the blocks to put in the collection + * @param {string} title The title to display in the block inserter + * @param {Object} icon (optional) The icon to display in the block inserter * * @return {Object} Action object. */ @@ -208,7 +208,7 @@ export function addBlockCollection( namespace, title, icon ) { /** * Returns an action object used to remove block collections * - * @param {string} namespace The namespace of the blocks to put in the collection + * @param {string} namespace The namespace of the blocks to put in the collection * * @return {Object} Action object. */ diff --git a/packages/blocks/src/store/reducer.js b/packages/blocks/src/store/reducer.js index 3bbe4ea1fa561..7fdf97ba4b705 100644 --- a/packages/blocks/src/store/reducer.js +++ b/packages/blocks/src/store/reducer.js @@ -171,7 +171,7 @@ export function blockVariations( state = {}, action ) { /** * Higher-order Reducer creating a reducer keeping track of given block name. * - * @param {string} setActionType Action type. + * @param {string} setActionType Action type. * * @return {Function} Reducer. */ diff --git a/packages/blocks/src/store/selectors.js b/packages/blocks/src/store/selectors.js index 21e88311b522f..fc56333aa0b6d 100644 --- a/packages/blocks/src/store/selectors.js +++ b/packages/blocks/src/store/selectors.js @@ -55,7 +55,7 @@ export const getBlockTypes = createSelector( * Returns a block type by name. * * @param {Object} state Data state. - * @param {string} name Block type name. + * @param {string} name Block type name. * * @return {Object?} Block Type. */ @@ -201,10 +201,10 @@ export const getChildBlockNames = createSelector( /** * Returns the block support value for a feature, if defined. * - * @param {Object} state Data state. - * @param {(string|Object)} nameOrType Block name or type object - * @param {string} feature Feature to retrieve - * @param {*} defaultSupports Default value to return if not + * @param {Object} state Data state. + * @param {(string|Object)} nameOrType Block name or type object + * @param {string} feature Feature to retrieve + * @param {*} defaultSupports Default value to return if not * explicitly defined * * @return {?*} Block support value @@ -227,7 +227,7 @@ export const getBlockSupport = ( /** * Returns true if the block defines support for a feature, or false otherwise. * - * @param {Object} state Data state. + * @param {Object} state Data state. * @param {(string|Object)} nameOrType Block name or type object. * @param {string} feature Feature to test. * @param {boolean} defaultSupports Whether feature is supported by diff --git a/packages/components/src/alignment-matrix-control/utils.js b/packages/components/src/alignment-matrix-control/utils.js index 77d08b9f08059..379c61036d1af 100644 --- a/packages/components/src/alignment-matrix-control/utils.js +++ b/packages/components/src/alignment-matrix-control/utils.js @@ -47,7 +47,7 @@ export function transformValue( value ) { * Creates an item ID based on a prefix ID and an alignment value. * * @param {string} prefixId An ID to prefix. - * @param {string} value An alignment value. + * @param {string} value An alignment value. * * @return {string} The item id. */ diff --git a/packages/components/src/autocomplete/index.js b/packages/components/src/autocomplete/index.js index 38a5a0d58fd6b..087bb7ea53c5d 100644 --- a/packages/components/src/autocomplete/index.js +++ b/packages/components/src/autocomplete/index.js @@ -75,7 +75,7 @@ import withSpokenMessages from '../higher-order/with-spoken-messages'; /** * @typedef {Object} OptionCompletion * @property {'insert-at-caret'|'replace'} action the intended placement of the completion. - * @property {OptionCompletionValue} value the completion value. + * @property {OptionCompletionValue} value the completion value. */ /** @@ -87,7 +87,7 @@ import withSpokenMessages from '../higher-order/with-spoken-messages'; /** * @callback FnGetOptionCompletion * @param {CompleterOption} value the value of the completer option. - * @param {string} query the text value of the autocomplete query. + * @param {string} query the text value of the autocomplete query. * * @return {(OptionCompletion|OptionCompletionValue)} the completion for the given option. If an * OptionCompletionValue is returned, the @@ -96,15 +96,15 @@ import withSpokenMessages from '../higher-order/with-spoken-messages'; /** * @typedef {Object} WPCompleter - * @property {string} name a way to identify a completer, useful for selective overriding. - * @property {?string} className A class to apply to the popup menu. - * @property {string} triggerPrefix the prefix that will display the menu. - * @property {(CompleterOption[]|FnGetOptions)} options the completer options or a function to get them. - * @property {?FnGetOptionKeywords} getOptionKeywords get the keywords for a given option. - * @property {?FnIsOptionDisabled} isOptionDisabled get whether or not the given option is disabled. - * @property {FnGetOptionLabel} getOptionLabel get the label for a given option. - * @property {?FnAllowContext} allowContext filter the context under which the autocomplete activates. - * @property {FnGetOptionCompletion} getOptionCompletion get the completion associated with a given option. + * @property {string} name a way to identify a completer, useful for selective overriding. + * @property {?string} className A class to apply to the popup menu. + * @property {string} triggerPrefix the prefix that will display the menu. + * @property {(CompleterOption[]|FnGetOptions)} options the completer options or a function to get them. + * @property {?FnGetOptionKeywords} getOptionKeywords get the keywords for a given option. + * @property {?FnIsOptionDisabled} isOptionDisabled get whether or not the given option is disabled. + * @property {FnGetOptionLabel} getOptionLabel get the label for a given option. + * @property {?FnAllowContext} allowContext filter the context under which the autocomplete activates. + * @property {FnGetOptionCompletion} getOptionCompletion get the completion associated with a given option. */ function filterOptions( search, options = [], maxResults = 10 ) { diff --git a/packages/components/src/color-picker/index.js b/packages/components/src/color-picker/index.js index 957a4e578e1f5..86fbdb9a544f1 100644 --- a/packages/components/src/color-picker/index.js +++ b/packages/components/src/color-picker/index.js @@ -71,25 +71,25 @@ const isValidColor = ( colors ) => * Function that creates the new color object * from old data and the new value. * - * @param {Object} oldColors The old color object. - * @param {string} oldColors.hex - * @param {Object} oldColors.rgb - * @param {number} oldColors.rgb.r - * @param {number} oldColors.rgb.g - * @param {number} oldColors.rgb.b - * @param {number} oldColors.rgb.a - * @param {Object} oldColors.hsl - * @param {number} oldColors.hsl.h - * @param {number} oldColors.hsl.s - * @param {number} oldColors.hsl.l - * @param {number} oldColors.hsl.a - * @param {string} oldColors.draftHex Same format as oldColors.hex - * @param {Object} oldColors.draftRgb Same format as oldColors.rgb - * @param {Object} oldColors.draftHsl Same format as oldColors.hsl - * @param {Object} data Data containing the new value to update. - * @param {Object} data.source One of `hex`, `rgb`, `hsl`. - * @param {string|number} data.value Value to update. - * @param {string} data.valueKey Depends on `data.source` values: + * @param {Object} oldColors The old color object. + * @param {string} oldColors.hex + * @param {Object} oldColors.rgb + * @param {number} oldColors.rgb.r + * @param {number} oldColors.rgb.g + * @param {number} oldColors.rgb.b + * @param {number} oldColors.rgb.a + * @param {Object} oldColors.hsl + * @param {number} oldColors.hsl.h + * @param {number} oldColors.hsl.s + * @param {number} oldColors.hsl.l + * @param {number} oldColors.hsl.a + * @param {string} oldColors.draftHex Same format as oldColors.hex + * @param {Object} oldColors.draftRgb Same format as oldColors.rgb + * @param {Object} oldColors.draftHsl Same format as oldColors.hsl + * @param {Object} data Data containing the new value to update. + * @param {Object} data.source One of `hex`, `rgb`, `hsl`. + * @param {string|number} data.value Value to update. + * @param {string} data.valueKey Depends on `data.source` values: * - when source = `rgb`, valuKey can be `r`, `g`, `b`, or `a`. * - when source = `hsl`, valuKey can be `h`, `s`, `l`, or `a`. * @return {Object} A new color object for a specific source. For example: diff --git a/packages/components/src/color-picker/utils.js b/packages/components/src/color-picker/utils.js index 03f2ccc9efd57..e59576cfeda3c 100644 --- a/packages/components/src/color-picker/utils.js +++ b/packages/components/src/color-picker/utils.js @@ -34,8 +34,8 @@ import tinycolor from 'tinycolor2'; /** * Given a hex color, get all other color properties (rgb, alpha, etc). * - * @param {Object|string} data A hex color string or an object with a hex property - * @param {string} oldHue A reference to the hue of the previous color, otherwise dragging the saturation to zero will reset the current hue to zero as well. See https://github.com/casesandberg/react-color/issues/29#issuecomment-132686909. + * @param {Object|string} data A hex color string or an object with a hex property + * @param {string} oldHue A reference to the hue of the previous color, otherwise dragging the saturation to zero will reset the current hue to zero as well. See https://github.com/casesandberg/react-color/issues/29#issuecomment-132686909. * @return {Object} An object of different color representations. */ export function colorToState( data = {}, oldHue = false ) { @@ -70,7 +70,7 @@ export function colorToState( data = {}, oldHue = false ) { /** * Get the top/left offsets of a point in a container, also returns the container width/height. * - * @param {Event} e Mouse or touch event with a location coordinate. + * @param {Event} e Mouse or touch event with a location coordinate. * @param {HTMLElement} container The container div, returned point is relative to this container. * @return {Object} An object of the offset positions & container size. */ @@ -140,8 +140,8 @@ export function simpleCheckForValidColor( data ) { /** * Calculate the current alpha based on a mouse or touch event * - * @param {Event} e A mouse or touch event on the alpha bar. - * @param {Object} props The current component props + * @param {Event} e A mouse or touch event on the alpha bar. + * @param {Object} props The current component props * @param {HTMLElement} container The container div for the alpha bar graph. * @return {Object|null} If the alpha value has changed, returns a new color object. */ @@ -164,8 +164,8 @@ export function calculateAlphaChange( e, props, container ) { /** * Calculate the current hue based on a mouse or touch event * - * @param {Event} e A mouse or touch event on the hue bar. - * @param {Object} props The current component props + * @param {Event} e A mouse or touch event on the hue bar. + * @param {Object} props The current component props * @param {HTMLElement} container The container div for the hue bar graph. * @return {Object|null} If the hue value has changed, returns a new color object. */ @@ -189,8 +189,8 @@ export function calculateHueChange( e, props, container ) { /** * Calculate the current saturation & brightness based on a mouse or touch event * - * @param {Event} e A mouse or touch event on the saturation graph. - * @param {Object} props The current component props + * @param {Event} e A mouse or touch event on the saturation graph. + * @param {Object} props The current component props * @param {HTMLElement} container The container div for the 2D saturation graph. * @return {Object} Returns a new color object. */ diff --git a/packages/components/src/dimension-control/sizes.js b/packages/components/src/dimension-control/sizes.js index f1d768894dda2..e294f5b211903 100644 --- a/packages/components/src/dimension-control/sizes.js +++ b/packages/components/src/dimension-control/sizes.js @@ -16,8 +16,8 @@ import { __ } from '@wordpress/i18n'; * Finds the correct size object from the provided sizes * table by size slug (eg: `medium`) * - * @param {Array} sizes containing objects for each size definition - * @param {string} slug a string representation of the size (eg: `medium`) + * @param {Array} sizes containing objects for each size definition + * @param {string} slug a string representation of the size (eg: `medium`) * @return {Object} the matching size definition */ export const findSizeBySlug = ( sizes, slug ) => diff --git a/packages/components/src/draggable/index.js b/packages/components/src/draggable/index.js index 251eeeb8848c6..9d205cc0c9818 100644 --- a/packages/components/src/draggable/index.js +++ b/packages/components/src/draggable/index.js @@ -32,7 +32,7 @@ class Draggable extends Component { /** * Removes the element clone, resets cursor, and removes drag listener. * - * @param {Object} event The non-custom DragEvent. + * @param {Object} event The non-custom DragEvent. */ onDragEnd( event ) { const { onDragEnd = noop } = this.props; @@ -49,7 +49,7 @@ class Draggable extends Component { /** * Updates positioning of element clone based on mouse movement during dragging. * - * @param {Object} event The non-custom DragEvent. + * @param {Object} event The non-custom DragEvent. */ onDragOver( event ) { this.cloneWrapper.style.top = `${ @@ -82,7 +82,7 @@ class Draggable extends Component { * - Sets transfer data. * - Adds dragover listener. * - * @param {Object} event The non-custom DragEvent. + * @param {Object} event The non-custom DragEvent. */ onDragStart( event ) { const { diff --git a/packages/components/src/higher-order/with-notices/index.js b/packages/components/src/higher-order/with-notices/index.js index 0a1280438282c..469090e0e8cf2 100644 --- a/packages/components/src/higher-order/with-notices/index.js +++ b/packages/components/src/higher-order/with-notices/index.js @@ -17,7 +17,7 @@ import NoticeList from '../../notice/list'; /** * Override the default edit UI to include notices if supported. * - * @param {WPComponent} OriginalComponent Original component. + * @param {WPComponent} OriginalComponent Original component. * * @return {WPComponent} Wrapped component. */ @@ -46,7 +46,7 @@ export default createHigherOrderComponent( ( OriginalComponent ) => { /** * Function passed down as a prop that adds a new notice. * - * @param {Object} notice Notice to add. + * @param {Object} notice Notice to add. */ createNotice( notice ) { const noticeToAdd = notice.id ? notice : { ...notice, id: uuid() }; @@ -58,7 +58,7 @@ export default createHigherOrderComponent( ( OriginalComponent ) => { /** * Function passed as a prop that adds a new error notice. * - * @param {string} msg Error message of the notice. + * @param {string} msg Error message of the notice. */ createErrorNotice( msg ) { this.createNotice( { status: 'error', content: msg } ); @@ -67,7 +67,7 @@ export default createHigherOrderComponent( ( OriginalComponent ) => { /** * Removes a notice by id. * - * @param {string} id Id of the notice to remove. + * @param {string} id Id of the notice to remove. */ removeNotice( id ) { this.setState( ( state ) => ( { diff --git a/packages/components/src/higher-order/with-spoken-messages/index.js b/packages/components/src/higher-order/with-spoken-messages/index.js index 6649fc0337cb0..4d9f665d7ebbb 100644 --- a/packages/components/src/higher-order/with-spoken-messages/index.js +++ b/packages/components/src/higher-order/with-spoken-messages/index.js @@ -14,7 +14,7 @@ import { createHigherOrderComponent } from '@wordpress/compose'; * A Higher Order Component used to be provide a unique instance ID by * component. * - * @param {WPComponent} WrappedComponent The wrapped component. + * @param {WPComponent} WrappedComponent The wrapped component. * * @return {WPComponent} The component to be rendered. */ diff --git a/packages/components/src/input-control/state.js b/packages/components/src/input-control/state.js index b2cd3cc5225d2..b5708a1d9685f 100644 --- a/packages/components/src/input-control/state.js +++ b/packages/components/src/input-control/state.js @@ -56,7 +56,7 @@ function mergeInitialState( initialState = initialInputControlState ) { * Composes multiple stateReducers into a single stateReducer, building * the pipeline to control the flow for state and actions. * - * @param {...Function} fns State reducers. + * @param {...Function} fns State reducers. * @return {Function} The single composed stateReducer. */ export const composeStateReducers = ( ...fns ) => { @@ -169,7 +169,7 @@ function inputControlStateReducer( composedStateReducers ) { * https://kentcdodds.com/blog/the-state-reducer-pattern/ * * @param {Function} stateReducer An external state reducer. - * @param {Object} initialState The initial state for the reducer. + * @param {Object} initialState The initial state for the reducer. * @return {Object} State, dispatch, and a collection of actions. */ export function useInputControlStateReducer( diff --git a/packages/components/src/input-control/utils.js b/packages/components/src/input-control/utils.js index cb1049f56f060..f52285a30f2f3 100644 --- a/packages/components/src/input-control/utils.js +++ b/packages/components/src/input-control/utils.js @@ -30,8 +30,8 @@ export function getDragCursor( dragDirection ) { /** * Custom hook that renders a drag cursor when dragging. * - * @param {boolean} isDragging The dragging state. - * @param {string} dragDirection The drag direction. + * @param {boolean} isDragging The dragging state. + * @param {string} dragDirection The drag direction. * * @return {string} The CSS cursor value. */ diff --git a/packages/components/src/notice/list.js b/packages/components/src/notice/list.js index 64c68cbaede0e..3f1ec2ccec9c7 100644 --- a/packages/components/src/notice/list.js +++ b/packages/components/src/notice/list.js @@ -12,11 +12,11 @@ import Notice from './'; /** * Renders a list of notices. * - * @param {Object} $0 Props passed to the component. - * @param {Array} $0.notices Array of notices to render. - * @param {Function} $0.onRemove Function called when a notice should be removed / dismissed. - * @param {Object} $0.className Name of the class used by the component. - * @param {Object} $0.children Array of children to be rendered inside the notice list. + * @param {Object} $0 Props passed to the component. + * @param {Array} $0.notices Array of notices to render. + * @param {Function} $0.onRemove Function called when a notice should be removed / dismissed. + * @param {Object} $0.className Name of the class used by the component. + * @param {Object} $0.children Array of children to be rendered inside the notice list. * @return {Object} The rendered notices list. */ function NoticeList( { notices, onRemove = noop, className, children } ) { diff --git a/packages/components/src/number-control/index.js b/packages/components/src/number-control/index.js index 15adad91b628a..5986c1749d3da 100644 --- a/packages/components/src/number-control/index.js +++ b/packages/components/src/number-control/index.js @@ -57,7 +57,7 @@ export function NumberControl( * This allows us to tap into actions to transform the (next) state for * InputControl. * - * @param {Object} state State from InputControl + * @param {Object} state State from InputControl * @param {Object} action Action triggering state change * @return {Object} The updated state to apply to InputControl */ diff --git a/packages/components/src/query-controls/terms.js b/packages/components/src/query-controls/terms.js index 60cfdd8563d0b..6405cf5d1ba5b 100644 --- a/packages/components/src/query-controls/terms.js +++ b/packages/components/src/query-controls/terms.js @@ -6,7 +6,7 @@ import { groupBy } from 'lodash'; /** * Returns terms in a tree form. * - * @param {Array} flatTerms Array of terms in flat format. + * @param {Array} flatTerms Array of terms in flat format. * * @return {Array} Array of terms in tree format. */ diff --git a/packages/components/src/resizable-box/resize-tooltip/utils.js b/packages/components/src/resizable-box/resize-tooltip/utils.js index f0ec585d99c6f..db02fbb36dafb 100644 --- a/packages/components/src/resizable-box/resize-tooltip/utils.js +++ b/packages/components/src/resizable-box/resize-tooltip/utils.js @@ -19,20 +19,20 @@ export const POSITIONS = { /** * @typedef {Object} UseResizeLabelProps * - * @property {undefined|string} label The label value. - * @property {Function} resizeListener Element to be rendered for resize listening events. + * @property {undefined|string} label The label value. + * @property {Function} resizeListener Element to be rendered for resize listening events. */ /** * Custom hook that manages resize listener events. It also provides a label * based on current resize width x height values. * - * @param {Object} props - * @param {string} props.axis Only shows the label corresponding to the axis. - * @param {number} props.fadeTimeout Duration (ms) before deactivating the resize label. - * @param {boolean} props.onResize Callback when a resize occurs. Provides { width, height } callback. - * @param {string} props.position Adjusts label value. - * @param {boolean} props.showPx Whether to add `PX` to the label. + * @param {Object} props + * @param {string} props.axis Only shows the label corresponding to the axis. + * @param {number} props.fadeTimeout Duration (ms) before deactivating the resize label. + * @param {boolean} props.onResize Callback when a resize occurs. Provides { width, height } callback. + * @param {string} props.position Adjusts label value. + * @param {boolean} props.showPx Whether to add `PX` to the label. * * @return {UseResizeLabelProps} Properties for hook. */ @@ -159,14 +159,14 @@ export function useResizeLabel( { /** * Gets the resize label based on width and height values (as well as recent changes). * - * @param {Object} props - * @param {string} props.axis Only shows the label corresponding to the axis. - * @param {number} props.height Height value. - * @param {boolean} props.moveX Recent width (x axis) changes. - * @param {boolean} props.moveY Recent width (y axis) changes. - * @param {string} props.position Adjusts label value. - * @param {boolean} props.showPx Whether to add `PX` to the label. - * @param {number} props.width Width value. + * @param {Object} props + * @param {string} props.axis Only shows the label corresponding to the axis. + * @param {number} props.height Height value. + * @param {boolean} props.moveX Recent width (x axis) changes. + * @param {boolean} props.moveY Recent width (y axis) changes. + * @param {string} props.position Adjusts label value. + * @param {boolean} props.showPx Whether to add `PX` to the label. + * @param {number} props.width Width value. * * @return {undefined | string} The rendered label. */ diff --git a/packages/components/src/scroll-lock/index.js b/packages/components/src/scroll-lock/index.js index 2808f434389a2..46e946cf25d3b 100644 --- a/packages/components/src/scroll-lock/index.js +++ b/packages/components/src/scroll-lock/index.js @@ -9,9 +9,9 @@ import { Component } from '@wordpress/element'; * This function creates a ScrollLock component for the specified document * and is exposed so we can create an isolated component for unit testing. * - * @param {Object} args Keyword args. + * @param {Object} args Keyword args. * @param {HTMLDocument} args.htmlDocument The document to lock the scroll for. - * @param {string} args.className The name of the class used to lock scrolling. + * @param {string} args.className The name of the class used to lock scrolling. * @return {WPComponent} The bound ScrollLock component. */ export function createScrollLockComponent( { diff --git a/packages/components/src/snackbar/list.js b/packages/components/src/snackbar/list.js index 1246822590fcc..91a56fc3bedcb 100644 --- a/packages/components/src/snackbar/list.js +++ b/packages/components/src/snackbar/list.js @@ -19,11 +19,11 @@ import Snackbar from './'; /** * Renders a list of notices. * - * @param {Object} $0 Props passed to the component. - * @param {Array} $0.notices Array of notices to render. - * @param {Function} $0.onRemove Function called when a notice should be removed / dismissed. - * @param {Object} $0.className Name of the class used by the component. - * @param {Object} $0.children Array of children to be rendered inside the notice list. + * @param {Object} $0 Props passed to the component. + * @param {Array} $0.notices Array of notices to render. + * @param {Function} $0.onRemove Function called when a notice should be removed / dismissed. + * @param {Object} $0.className Name of the class used by the component. + * @param {Object} $0.children Array of children to be rendered inside the notice list. * @return {Object} The rendered notices list. */ function SnackbarList( { notices, className, children, onRemove = noop } ) { diff --git a/packages/components/src/toolbar/index.js b/packages/components/src/toolbar/index.js index b94886bd9ce74..87d708089f13d 100644 --- a/packages/components/src/toolbar/index.js +++ b/packages/components/src/toolbar/index.js @@ -20,10 +20,10 @@ import ToolbarContainer from './toolbar-container'; * * To add controls, simply pass `ToolbarButton` components as children. * - * @param {Object} props Component props. + * @param {Object} props Component props. * @param {string} [props.className] Class to set on the container div. - * @param {string} [props.label] ARIA label for toolbar container. - * @param {Object} ref React Element ref. + * @param {string} [props.label] ARIA label for toolbar container. + * @param {Object} ref React Element ref. */ function Toolbar( { className, label, ...props }, ref ) { if ( ! label ) { diff --git a/packages/components/src/unit-control/index.js b/packages/components/src/unit-control/index.js index 435bc5cca466e..e9e98e5c04a13 100644 --- a/packages/components/src/unit-control/index.js +++ b/packages/components/src/unit-control/index.js @@ -112,7 +112,7 @@ function UnitControl( * This allows us to tap into actions to transform the (next) state for * InputControl. * - * @param {Object} state State from InputControl + * @param {Object} state State from InputControl * @param {Object} action Action triggering state change * @return {Object} The updated state to apply to InputControl */ diff --git a/packages/components/src/unit-control/utils.js b/packages/components/src/unit-control/utils.js index 8abd21dea85bf..eff92d0d68d00 100644 --- a/packages/components/src/unit-control/utils.js +++ b/packages/components/src/unit-control/utils.js @@ -22,7 +22,7 @@ export const DEFAULT_UNIT = CSS_UNITS[ 0 ]; * the value and unit, example: '10px' * * @param {number|string} value Value - * @param {string} unit Unit value + * @param {string} unit Unit value * @param {Array} units Units to derive from. * @return {Array} The extracted number and unit. */ @@ -45,8 +45,8 @@ export function hasUnits( units ) { /** * Parses a number and unit from a value. * - * @param {string} initialValue Value to parse - * @param {Array} units Units to derive from. + * @param {string} initialValue Value to parse + * @param {Array} units Units to derive from. * @return {Array} The extracted number and unit. */ export function parseUnit( initialValue, units = CSS_UNITS ) { @@ -74,10 +74,10 @@ export function parseUnit( initialValue, units = CSS_UNITS ) { * Parses a number and unit from a value. Validates parsed value, using fallback * value if invalid. * - * @param {number|string} next The next value. - * @param {Array} units Units to derive from. + * @param {number|string} next The next value. + * @param {Array} units Units to derive from. * @param {number|string} fallbackValue The fallback value. - * @param {string} fallbackUnit The fallback value. + * @param {string} fallbackUnit The fallback value. * @return {Array} The extracted number and unit. */ export function getValidParsedUnit( next, units, fallbackValue, fallbackUnit ) { diff --git a/packages/components/src/utils/colors.js b/packages/components/src/utils/colors.js index 43518ce29de14..93afef443c007 100644 --- a/packages/components/src/utils/colors.js +++ b/packages/components/src/utils/colors.js @@ -13,7 +13,7 @@ import { COLORS } from './colors-values'; * Generating a CSS complient rgba() color value. * * @param {string} hexValue The hex value to convert to rgba(). - * @param {number} alpha The alpha value for opacity. + * @param {number} alpha The alpha value for opacity. * @return {string} The converted rgba() color value. * * @example diff --git a/packages/components/src/utils/hooks/use-controlled-state.js b/packages/components/src/utils/hooks/use-controlled-state.js index f07c916d7f1c2..55ec6c707f8eb 100644 --- a/packages/components/src/utils/hooks/use-controlled-state.js +++ b/packages/components/src/utils/hooks/use-controlled-state.js @@ -33,10 +33,10 @@ const defaultOptions = { * Unlike the basic useState hook, useControlledState's state can * be updated if a new incoming prop value is changed. * - * @param {any} currentState The current value. - * @param {Object} options Additional options for the hook. - * @param {any} options.initial The initial state. - * @param {any} options.fallback The state to use when no state is defined. + * @param {any} currentState The current value. + * @param {Object} options Additional options for the hook. + * @param {any} options.initial The initial state. + * @param {any} options.fallback The state to use when no state is defined. * * @return {[*, Function]} The controlled value and the value setter. */ diff --git a/packages/components/src/utils/hooks/use-jump-step.js b/packages/components/src/utils/hooks/use-jump-step.js index f3ac123f6c8cf..25ed6f07fa02e 100644 --- a/packages/components/src/utils/hooks/use-jump-step.js +++ b/packages/components/src/utils/hooks/use-jump-step.js @@ -14,10 +14,10 @@ import { useEffect, useState } from '@wordpress/element'; * Holding down shift... * Starting from 10, the next incremented value will be 20. * - * @param {Object} props Properties for the hook. + * @param {Object} props Properties for the hook. * @param {boolean} [props.isShiftStepEnabled=true] Determines if jumping values with shift is enabled - * @param {number} [props.shiftStep=10] Multiplier to jump by, when holding shift key. - * @param {number} [props.step=1] Multiplier to jump by, when not-holding shift key. + * @param {number} [props.shiftStep=10] Multiplier to jump by, when holding shift key. + * @param {number} [props.step=1] Multiplier to jump by, when not-holding shift key. * * @return {number} The jump step value. */ diff --git a/packages/components/src/utils/math.js b/packages/components/src/utils/math.js index dad8c508a2167..a01af9b52a1b0 100644 --- a/packages/components/src/utils/math.js +++ b/packages/components/src/utils/math.js @@ -57,9 +57,9 @@ function getPrecision( value ) { * Clamps a value based on a min/max range with rounding * * @param {number} value The value. - * @param {number} min The minimum range. - * @param {number} max The maximum range. - * @param {number} step A multiplier for the value. + * @param {number} min The minimum range. + * @param {number} max The maximum range. + * @param {number} step A multiplier for the value. * * @return {number} The rounded and clamped value. */ @@ -86,9 +86,9 @@ export function roundClamp( * * @param {any} args Arguments for roundClamp(). * @property {number} value The value. - * @property {number} min The minimum range. - * @property {number} max The maximum range. - * @property {number} step A multiplier for the value. + * @property {number} min The minimum range. + * @property {number} max The maximum range. + * @property {number} step A multiplier for the value. * * @return {string} The rounded and clamped value. */ diff --git a/packages/components/src/utils/rtl.js b/packages/components/src/utils/rtl.js index 88a3f651af96c..af7accdcb3f96 100644 --- a/packages/components/src/utils/rtl.js +++ b/packages/components/src/utils/rtl.js @@ -76,7 +76,7 @@ export const convertLTRToRTL = ( ltrStyles = {} ) => { /** * A higher-order function that create an incredibly basic ltr -> rtl style converter for CSS objects. * - * @param {Object} ltrStyles Ltr styles. Converts and renders from ltr -> rtl styles, if applicable. + * @param {Object} ltrStyles Ltr styles. Converts and renders from ltr -> rtl styles, if applicable. * @param {null|Object} rtlStyles Rtl styles. Renders if provided. * * @return {Function} A function to output CSS styles for Emotion's renderer diff --git a/packages/components/src/utils/values.js b/packages/components/src/utils/values.js index d8d6375029027..c07cf50462040 100644 --- a/packages/components/src/utils/values.js +++ b/packages/components/src/utils/values.js @@ -23,8 +23,8 @@ export function isValueEmpty( value ) { /** * Attempts to get a defined/non-null value from a collection of arguments. * - * @param {Array} values Values to derive from. - * @param {any} fallbackValue Fallback value if there are no defined values. + * @param {Array} values Values to derive from. + * @param {any} fallbackValue Fallback value if there are no defined values. * @return {any} A defined value or the fallback value. */ export function getDefinedValue( values = [], fallbackValue ) { diff --git a/packages/compose/src/hooks/use-keyboard-shortcut/index.js b/packages/compose/src/hooks/use-keyboard-shortcut/index.js index 294823c144009..672fb45f8548a 100644 --- a/packages/compose/src/hooks/use-keyboard-shortcut/index.js +++ b/packages/compose/src/hooks/use-keyboard-shortcut/index.js @@ -15,16 +15,16 @@ import { useEffect, useRef } from '@wordpress/element'; * * @typedef {Object} WPKeyboardShortcutConfig * - * @property {boolean} [bindGlobal] Handle keyboard events anywhere including inside textarea/input fields. - * @property {string} [eventName] Event name used to trigger the handler, defaults to keydown. - * @property {boolean} [isDisabled] Disables the keyboard handler if the value is true. - * @property {Object} [target] React reference to the DOM element used to catch the keyboard event. + * @property {boolean} [bindGlobal] Handle keyboard events anywhere including inside textarea/input fields. + * @property {string} [eventName] Event name used to trigger the handler, defaults to keydown. + * @property {boolean} [isDisabled] Disables the keyboard handler if the value is true. + * @property {Object} [target] React reference to the DOM element used to catch the keyboard event. */ /** * Return true if platform is MacOS. * - * @param {Object} _window window object by default; used for DI testing. + * @param {Object} _window window object by default; used for DI testing. * * @return {boolean} True if MacOS; false otherwise. */ @@ -40,9 +40,9 @@ function isAppleOS( _window = window ) { /** * Attach a keyboard shortcut handler. * - * @param {string[]|string} shortcuts Keyboard Shortcuts. - * @param {Function} callback Shortcut callback. - * @param {WPKeyboardShortcutConfig} options Shortcut options. + * @param {string[]|string} shortcuts Keyboard Shortcuts. + * @param {Function} callback Shortcut callback. + * @param {WPKeyboardShortcutConfig} options Shortcut options. */ function useKeyboardShortcut( shortcuts, diff --git a/packages/core-data/src/actions.js b/packages/core-data/src/actions.js index 3027b1739bc7e..5ef0f9f43db04 100644 --- a/packages/core-data/src/actions.js +++ b/packages/core-data/src/actions.js @@ -48,7 +48,7 @@ export function receiveCurrentUser( currentUser ) { /** * Returns an action object used in adding new entities. * - * @param {Array} entities Entities received. + * @param {Array} entities Entities received. * * @return {Object} Action object. */ @@ -131,8 +131,8 @@ export function receiveThemeSupports( themeSupports ) { * Returns an action object used in signalling that the preview data for * a given URl has been received. * - * @param {string} url URL to preview the embed for. - * @param {*} preview Preview data. + * @param {string} url URL to preview the embed for. + * @param {*} preview Preview data. * * @return {Object} Action object. */ @@ -147,10 +147,10 @@ export function receiveEmbedPreview( url, preview ) { /** * Action triggered to delete an entity record. * - * @param {string} kind Kind of the deleted entity. - * @param {string} name Name of the deleted entity. - * @param {string} recordId Record ID of the deleted entity. - * @param {?Object} query Special query parameters for the DELETE API call. + * @param {string} kind Kind of the deleted entity. + * @param {string} name Name of the deleted entity. + * @param {string} recordId Record ID of the deleted entity. + * @param {?Object} query Special query parameters for the DELETE API call. */ export function* deleteEntityRecord( kind, name, recordId, query ) { const entities = yield getKindEntities( kind ); @@ -200,11 +200,11 @@ export function* deleteEntityRecord( kind, name, recordId, query ) { * Returns an action object that triggers an * edit to an entity record. * - * @param {string} kind Kind of the edited entity record. - * @param {string} name Name of the edited entity record. - * @param {number} recordId Record ID of the edited entity record. - * @param {Object} edits The edits. - * @param {Object} options Options for the edit. + * @param {string} kind Kind of the edited entity record. + * @param {string} name Name of the edited entity record. + * @param {number} recordId Record ID of the edited entity record. + * @param {Object} edits The edits. + * @param {Object} options Options for the edit. * @param {boolean} options.undoIgnore Whether to ignore the edit in undo history or not. * * @return {Object} Action object. diff --git a/packages/core-data/src/entities.js b/packages/core-data/src/entities.js index 061ff7e8ef4ad..0d04d6555b48d 100644 --- a/packages/core-data/src/entities.js +++ b/packages/core-data/src/entities.js @@ -183,7 +183,7 @@ export const getMethodName = ( /** * Loads the kind entities into the store. * - * @param {string} kind Kind + * @param {string} kind Kind * * @return {Array} Entities */ diff --git a/packages/core-data/src/queried-data/actions.js b/packages/core-data/src/queried-data/actions.js index d44d7876dd112..18e2afdbade12 100644 --- a/packages/core-data/src/queried-data/actions.js +++ b/packages/core-data/src/queried-data/actions.js @@ -21,10 +21,10 @@ export function receiveItems( items ) { * Returns an action object used in signalling that entity records have been * deleted and they need to be removed from entities state. * - * @param {string} kind Kind of the removed entities. - * @param {string} name Name of the removed entities. - * @param {Array|number} records Record IDs of the removed entities. - * @param {boolean} invalidateCache Controls whether we want to invalidate the cache. + * @param {string} kind Kind of the removed entities. + * @param {string} name Name of the removed entities. + * @param {Array|number} records Record IDs of the removed entities. + * @param {boolean} invalidateCache Controls whether we want to invalidate the cache. * @return {Object} Action object. */ export function removeItems( kind, name, records, invalidateCache = false ) { diff --git a/packages/core-data/src/queried-data/reducer.js b/packages/core-data/src/queried-data/reducer.js index 9198b9f16fa12..4c9455da3f623 100644 --- a/packages/core-data/src/queried-data/reducer.js +++ b/packages/core-data/src/queried-data/reducer.js @@ -101,7 +101,7 @@ function items( state = {}, action ) { * safe to use queried data for a non-`_fields`-limited request. * * @param {Object} state Current state. - * @param {Object} action Dispatched action. + * @param {Object} action Dispatched action. * * @return {Object} Next state. */ diff --git a/packages/core-data/src/reducer.js b/packages/core-data/src/reducer.js index 8238c42380da9..3b4318aa21029 100644 --- a/packages/core-data/src/reducer.js +++ b/packages/core-data/src/reducer.js @@ -166,7 +166,7 @@ export function themeSupports( state = {}, action ) { * - Editing * - Saving * - * @param {Object} entityConfig Entity config. + * @param {Object} entityConfig Entity config. * * @return {Function} Reducer. */ @@ -515,8 +515,8 @@ export function embedPreviews( state = {}, action ) { * State which tracks whether the user can perform an action on a REST * resource. * - * @param {Object} state Current state. - * @param {Object} action Dispatched action. + * @param {Object} state Current state. + * @param {Object} action Dispatched action. * * @return {Object} Updated state. */ @@ -535,8 +535,8 @@ export function userPermissions( state = {}, action ) { /** * Reducer returning autosaves keyed by their parent's post id. * - * @param {Object} state Current state. - * @param {Object} action Dispatched action. + * @param {Object} state Current state. + * @param {Object} action Dispatched action. * * @return {Object} Updated state. */ diff --git a/packages/core-data/src/resolvers.js b/packages/core-data/src/resolvers.js index e756895cd0283..7718b7d40f6d2 100644 --- a/packages/core-data/src/resolvers.js +++ b/packages/core-data/src/resolvers.js @@ -130,9 +130,9 @@ export const getEditedEntityRecord = ifNotResolved( /** * Requests the entity's records from the REST API. * - * @param {string} kind Entity kind. - * @param {string} name Entity name. - * @param {Object?} query Query Object. + * @param {string} kind Entity kind. + * @param {string} name Entity name. + * @param {Object?} query Query Object. */ export function* getEntityRecords( kind, name, query = {} ) { const entities = yield getKindEntities( kind ); @@ -210,7 +210,7 @@ export function* getThemeSupports() { /** * Requests a preview from the from the Embed API. * - * @param {string} url URL to get the preview for. + * @param {string} url URL to get the preview for. */ export function* getEmbedPreview( url ) { try { diff --git a/packages/core-data/src/selectors.js b/packages/core-data/src/selectors.js index 8eaedd8dbf1da..6db7b0b2abb3b 100644 --- a/packages/core-data/src/selectors.js +++ b/packages/core-data/src/selectors.js @@ -78,7 +78,7 @@ export const getUserQueryResults = createSelector( /** * Returns whether the entities for the give kind are loaded. * - * @param {Object} state Data state. + * @param {Object} state Data state. * @param {string} kind Entity kind. * * @return {boolean} Whether the entities are loaded @@ -90,7 +90,7 @@ export function getEntitiesByKind( state, kind ) { /** * Returns the entity object given its kind and name. * - * @param {Object} state Data state. + * @param {Object} state Data state. * @param {string} kind Entity kind. * @param {string} name Entity name. * @@ -139,10 +139,10 @@ export function getEntityRecord( state, kind, name, key, query ) { /** * Returns the Entity's record object by key. Doesn't trigger a resolver nor requests the entity from the API if the entity record isn't available in the local state. * - * @param {Object} state State tree - * @param {string} kind Entity kind. - * @param {string} name Entity name. - * @param {number} key Record's key + * @param {Object} state State tree + * @param {string} kind Entity kind. + * @param {string} name Entity name. + * @param {number} key Record's key * * @return {Object|null} Record. */ @@ -159,10 +159,10 @@ export function __experimentalGetEntityRecordNoResolver( * Returns the entity's record object by key, * with its attributes mapped to their raw values. * - * @param {Object} state State tree. - * @param {string} kind Entity kind. - * @param {string} name Entity name. - * @param {number} key Record's key. + * @param {Object} state State tree. + * @param {string} kind Entity kind. + * @param {string} name Entity name. + * @param {number} key Record's key. * * @return {Object?} Object with the entity's raw attributes. */ @@ -547,8 +547,8 @@ export function getThemeSupports( state ) { /** * Returns the embed preview for the given URL. * - * @param {Object} state Data state. - * @param {string} url Embedded URL. + * @param {Object} state Data state. + * @param {string} url Embedded URL. * * @return {*} Undefined if the preview has not been fetched, otherwise, the preview fetched from the embed preview API. */ @@ -563,8 +563,8 @@ export function getEmbedPreview( state, url ) { * We need to be able to determine if a URL is embeddable or not, based on what we * get back from the oEmbed preview API. * - * @param {Object} state Data state. - * @param {string} url Embedded URL. + * @param {Object} state Data state. + * @param {string} url Embedded URL. * * @return {boolean} Is the preview for the URL an oEmbed link fallback. */ @@ -609,10 +609,10 @@ export function hasUploadPermissions( state ) { * * https://developer.wordpress.org/rest-api/reference/ * - * @param {Object} state Data state. - * @param {string} action Action to check. One of: 'create', 'read', 'update', 'delete'. - * @param {string} resource REST resource to check, e.g. 'media' or 'posts'. - * @param {string=} id Optional ID of the rest resource to check. + * @param {Object} state Data state. + * @param {string} action Action to check. One of: 'create', 'read', 'update', 'delete'. + * @param {string} resource REST resource to check, e.g. 'media' or 'posts'. + * @param {string=} id Optional ID of the rest resource to check. * * @return {boolean|undefined} Whether or not the user can perform the action, * or `undefined` if the OPTIONS request is still being made. @@ -660,7 +660,7 @@ export function getAutosave( state, postType, postId, authorId ) { /** * Returns true if the REST request for autosaves has completed. * - * @param {Object} state State tree. + * @param {Object} state State tree. * @param {string} postType The type of the parent post. * @param {number} postId The id of the parent post. * diff --git a/packages/data-controls/src/index.js b/packages/data-controls/src/index.js index 91c97e4ec981d..4ca79b10db004 100644 --- a/packages/data-controls/src/index.js +++ b/packages/data-controls/src/index.js @@ -37,9 +37,9 @@ export const apiFetch = ( request ) => { * selectors that may have a resolver. It will await and return the resolved * value when the selector has not been resolved yet. * - * @param {string} storeKey The key for the store the selector belongs to - * @param {string} selectorName The name of the selector - * @param {Array} args Arguments for the select. + * @param {string} storeKey The key for the store the selector belongs to + * @param {string} selectorName The name of the selector + * @param {Array} args Arguments for the select. * * @example * ```js @@ -98,9 +98,9 @@ export function __unstableSyncSelect( storeKey, selectorName, ...args ) { /** * Dispatches a control action for triggering a registry dispatch. * - * @param {string} storeKey The key for the store the action belongs to - * @param {string} actionName The name of the action to dispatch - * @param {Array} args Arguments for the dispatch action. + * @param {string} storeKey The key for the store the action belongs to + * @param {string} actionName The name of the action to dispatch + * @param {Array} args Arguments for the dispatch action. * * @example * ```js diff --git a/packages/data/src/components/async-mode-provider/context.js b/packages/data/src/components/async-mode-provider/context.js index ff6528c324cc3..e8f21fe8a07df 100644 --- a/packages/data/src/components/async-mode-provider/context.js +++ b/packages/data/src/components/async-mode-provider/context.js @@ -40,7 +40,7 @@ export const AsyncModeConsumer = Consumer; * the rerendering is delayed until the browser becomes IDLE. * It is possible to nest multiple levels of AsyncModeProvider to fine-tune the rendering behavior. * - * @param {boolean} props.value Enable Async Mode. + * @param {boolean} props.value Enable Async Mode. * @return {WPComponent} The component to be rendered. */ export default Provider; diff --git a/packages/data/src/components/use-dispatch/use-dispatch-with-map.js b/packages/data/src/components/use-dispatch/use-dispatch-with-map.js index eda70d5846cff..6317a0e55626d 100644 --- a/packages/data/src/components/use-dispatch/use-dispatch-with-map.js +++ b/packages/data/src/components/use-dispatch/use-dispatch-with-map.js @@ -36,11 +36,11 @@ const useIsomorphicLayoutEffect = * * Currently this is an internal api only and is implemented by `withDispatch` * - * @param {Function} dispatchMap Receives the `registry.dispatch` function as + * @param {Function} dispatchMap Receives the `registry.dispatch` function as * the first argument and the `registry` object * as the second argument. Should return an * object mapping props to functions. - * @param {Array} deps An array of dependencies for the hook. + * @param {Array} deps An array of dependencies for the hook. * @return {Object} An object mapping props to functions created by the passed * in dispatchMap. */ diff --git a/packages/data/src/components/use-dispatch/use-dispatch.js b/packages/data/src/components/use-dispatch/use-dispatch.js index 9add695434be1..751a13c3bfac8 100644 --- a/packages/data/src/components/use-dispatch/use-dispatch.js +++ b/packages/data/src/components/use-dispatch/use-dispatch.js @@ -9,7 +9,7 @@ import useRegistry from '../registry-provider/use-registry'; * Note: The component using this hook must be within the context of a * RegistryProvider. * - * @param {string} [storeName] Optionally provide the name of the store from + * @param {string} [storeName] Optionally provide the name of the store from * which to retrieve action creators. If not * provided, the registry.dispatch function is * returned instead. diff --git a/packages/data/src/components/use-select/index.js b/packages/data/src/components/use-select/index.js index 0bcede5c9d777..b9ce45bdbf92e 100644 --- a/packages/data/src/components/use-select/index.js +++ b/packages/data/src/components/use-select/index.js @@ -41,13 +41,13 @@ const renderQueue = createQueue(); * In general, this custom React hook follows the * [rules of hooks](https://reactjs.org/docs/hooks-rules.html). * - * @param {Function} _mapSelect Function called on every state change. The + * @param {Function} _mapSelect Function called on every state change. The * returned value is exposed to the component * implementing this hook. The function receives * the `registry.select` method on the first * argument and the `registry` on the second * argument. - * @param {Array} deps If provided, this memoizes the mapSelect so the + * @param {Array} deps If provided, this memoizes the mapSelect so the * same `mapSelect` is invoked on every state * change unless the dependencies change. * diff --git a/packages/data/src/namespace-store/index.js b/packages/data/src/namespace-store/index.js index 3cf0919db018b..649fb694fe5f9 100644 --- a/packages/data/src/namespace-store/index.js +++ b/packages/data/src/namespace-store/index.js @@ -232,8 +232,8 @@ function mapSelectors( selectors, store ) { /** * Maps actions to dispatch from a given store. * - * @param {Object} actions Actions to register. - * @param {Object} store The redux store to which the actions should be mapped. + * @param {Object} actions Actions to register. + * @param {Object} store The redux store to which the actions should be mapped. * @return {Object} Actions mapped to the redux store provided. */ function mapActions( actions, store ) { @@ -337,7 +337,7 @@ function mapResolvers( resolvers, selectors, store, resolversCache ) { * @param {Object} store Store reference, for fulfilling via resolvers * @param {Object} resolvers Store Resolvers * @param {string} selectorName Selector name to fulfill. - * @param {Array} args Selector Arguments. + * @param {Array} args Selector Arguments. */ async function fulfillResolver( store, resolvers, selectorName, ...args ) { const resolver = get( resolvers, [ selectorName ] ); diff --git a/packages/data/src/namespace-store/metadata/reducer.js b/packages/data/src/namespace-store/metadata/reducer.js index 5f3e9e3f7f8d5..24a747f39fe33 100644 --- a/packages/data/src/namespace-store/metadata/reducer.js +++ b/packages/data/src/namespace-store/metadata/reducer.js @@ -45,8 +45,8 @@ const subKeysIsResolved = onSubKey( 'selectorName' )( * * selectorName -> EquivalentKeyMap * - * @param {Object} state Current state. - * @param {Object} action Dispatched action. + * @param {Object} state Current state. + * @param {Object} action Dispatched action. * * @return {Object} Next state. */ diff --git a/packages/data/src/namespace-store/metadata/selectors.js b/packages/data/src/namespace-store/metadata/selectors.js index 34217edcedd10..4983f049c8442 100644 --- a/packages/data/src/namespace-store/metadata/selectors.js +++ b/packages/data/src/namespace-store/metadata/selectors.js @@ -69,7 +69,7 @@ export function isResolving( state, selectorName, args = [] ) { /** * Returns the list of the cached resolvers. * - * @param {Object} state Data state. + * @param {Object} state Data state. * * @return {Object} Resolvers mapped by args and selectorName. */ diff --git a/packages/data/src/registry.js b/packages/data/src/registry.js index fe3eb80d7efd9..2c6b5fddb4b80 100644 --- a/packages/data/src/registry.js +++ b/packages/data/src/registry.js @@ -59,7 +59,7 @@ export function createRegistry( storeConfigs = {}, parent = null ) { /** * Subscribe to changes to any data. * - * @param {Function} listener Listener function. + * @param {Function} listener Listener function. * * @return {Function} Unsubscribe function. */ diff --git a/packages/docgen/src/engine.js b/packages/docgen/src/engine.js index 71d6436c462e8..0e653f6081353 100644 --- a/packages/docgen/src/engine.js +++ b/packages/docgen/src/engine.js @@ -43,7 +43,7 @@ const engine = ( path, code, getIRFromPath = () => {} ) => { /** * Function that takes code and returns an intermediate representation. * - * @param {string} code The code to parse. + * @param {string} code The code to parse. * @param {Function} [getIRFromPath=noop] Callback to retrieve the * Intermediate Representation from a path relative to the file * being parsed. diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js index 4e1e3fe97e4c5..dc43afb492020 100644 --- a/packages/docgen/src/get-intermediate-representation.js +++ b/packages/docgen/src/get-intermediate-representation.js @@ -121,9 +121,9 @@ const getJSDoc = ( token, entry, ast, parseDependency ) => { * the identifier declaration will be looked up in the file or dependency * if an `ast` and `parseDependency` callback are provided. * - * @param {string} path Path to file being processed. - * @param {Object} token Espree export token. - * @param {Object} [ast] Espree ast of the file being parsed. + * @param {string} path Path to file being processed. + * @param {Object} token Espree export token. + * @param {Object} [ast] Espree ast of the file being parsed. * @param {Function} [parseDependency] Function that takes a path * and returns the intermediate representation of the dependency file. * diff --git a/packages/docgen/src/markdown/embed.js b/packages/docgen/src/markdown/embed.js index aecd6b909ba4b..5b79c83932603 100644 --- a/packages/docgen/src/markdown/embed.js +++ b/packages/docgen/src/markdown/embed.js @@ -15,8 +15,8 @@ const getHeadingIndex = ( ast, index ) => { /** * Inserts new contents within the token boundaries. * - * @param {string} token String to embed in the start/end tokens. - * @param {Object} targetAst The remark AST of the file where the new contents are to be embedded. + * @param {string} token String to embed in the start/end tokens. + * @param {Object} targetAst The remark AST of the file where the new contents are to be embedded. * @param {Object} newContentAst The new contents to be embedded in remark AST format. * @return {boolean} Whether the contents were embedded or not. */ diff --git a/packages/docgen/src/test/fixtures/tags-function/code.js b/packages/docgen/src/test/fixtures/tags-function/code.js index 4e0bd9644fb90..00b529b8691f3 100644 --- a/packages/docgen/src/test/fixtures/tags-function/code.js +++ b/packages/docgen/src/test/fixtures/tags-function/code.js @@ -7,7 +7,7 @@ * @see addition * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators * - * @param {number} firstParam The first param to add. + * @param {number} firstParam The first param to add. * @param {number} secondParam The second param to add. * * @example diff --git a/packages/dom/src/dom.js b/packages/dom/src/dom.js index 5959863dbcf2c..63bc42786af8a 100644 --- a/packages/dom/src/dom.js +++ b/packages/dom/src/dom.js @@ -318,8 +318,8 @@ export function placeCaretAtHorizontalEdge( container, isReverse ) { * @see https://developer.mozilla.org/en-US/docs/Web/API/Document/caretRangeFromPoint * * @param {Document} doc The document of the range. - * @param {number} x Horizontal position within the current viewport. - * @param {number} y Vertical position within the current viewport. + * @param {number} x Horizontal position within the current viewport. + * @param {number} y Vertical position within the current viewport. * * @return {?Range} The best range for the given point. */ @@ -354,8 +354,8 @@ function caretRangeFromPoint( doc, x, y ) { * This is preferred over getting the UI nodes and set styles there. * * @param {Document} doc The document of the range. - * @param {number} x Horizontal position within the current viewport. - * @param {number} y Vertical position within the current viewport. + * @param {number} x Horizontal position within the current viewport. + * @param {number} y Vertical position within the current viewport. * @param {Element} container Container in which the range is expected to be found. * * @return {?Range} The best range for the given point. @@ -729,8 +729,8 @@ export function unwrap( node ) { /** * Replaces the given node with a new node with the given tag name. * - * @param {Element} node The node to replace - * @param {string} tagName The new tag name. + * @param {Element} node The node to replace + * @param {string} tagName The new tag name. * * @return {Element} The new node. */ diff --git a/packages/e2e-test-utils/src/create-url.js b/packages/e2e-test-utils/src/create-url.js index d608e75e306ae..edd94db48b468 100644 --- a/packages/e2e-test-utils/src/create-url.js +++ b/packages/e2e-test-utils/src/create-url.js @@ -11,8 +11,8 @@ import { WP_BASE_URL } from './shared/config'; /** * Creates new URL by parsing base URL, WPPath and query string. * - * @param {string} WPPath String to be serialized as pathname. - * @param {?string} query String to be serialized as query portion of URL. + * @param {string} WPPath String to be serialized as pathname. + * @param {?string} query String to be serialized as query portion of URL. * @return {string} String which represents full URL. */ export function createURL( WPPath, query = '' ) { diff --git a/packages/e2e-test-utils/src/install-plugin.js b/packages/e2e-test-utils/src/install-plugin.js index 6fa47ed53d8e4..a2f8e49329419 100644 --- a/packages/e2e-test-utils/src/install-plugin.js +++ b/packages/e2e-test-utils/src/install-plugin.js @@ -8,7 +8,7 @@ import { visitAdminPage } from './visit-admin-page'; /** * Installs a plugin from the WP.org repository. * - * @param {string} slug Plugin slug. + * @param {string} slug Plugin slug. * @param {string?} searchTerm If the plugin is not findable by its slug use an alternative term to search. */ export async function installPlugin( slug, searchTerm ) { diff --git a/packages/e2e-test-utils/src/is-current-url.js b/packages/e2e-test-utils/src/is-current-url.js index 002ce83b4c1e8..f1a47a6cd4ea1 100644 --- a/packages/e2e-test-utils/src/is-current-url.js +++ b/packages/e2e-test-utils/src/is-current-url.js @@ -6,8 +6,8 @@ import { createURL } from './create-url'; /** * Checks if current URL is a WordPress path. * - * @param {string} WPPath String to be serialized as pathname. - * @param {?string} query String to be serialized as query portion of URL. + * @param {string} WPPath String to be serialized as pathname. + * @param {?string} query String to be serialized as query portion of URL. * @return {boolean} Boolean represents whether current URL is or not a WordPress path. */ export function isCurrentURL( WPPath, query = '' ) { diff --git a/packages/e2e-test-utils/src/mocks/create-embedding-matcher.js b/packages/e2e-test-utils/src/mocks/create-embedding-matcher.js index 754d7bc33068e..35e8c85fb8838 100644 --- a/packages/e2e-test-utils/src/mocks/create-embedding-matcher.js +++ b/packages/e2e-test-utils/src/mocks/create-embedding-matcher.js @@ -7,7 +7,7 @@ import { join } from 'path'; * Creates a function to determine if a request has a parameter with a certain value. * * @param {string} parameterName The query parameter to check. - * @param {string} value The value to check for. + * @param {string} value The value to check for. * @return {Function} Function that determines if a request's query parameter is the specified value. */ function parameterEquals( parameterName, value ) { diff --git a/packages/e2e-test-utils/src/mocks/mock-or-transform.js b/packages/e2e-test-utils/src/mocks/mock-or-transform.js index 5b2a33de38cca..3607e66760e3a 100644 --- a/packages/e2e-test-utils/src/mocks/mock-or-transform.js +++ b/packages/e2e-test-utils/src/mocks/mock-or-transform.js @@ -12,8 +12,8 @@ import { getJSONResponse } from '../shared/get-json-response'; * Mocks a request with the supplied mock object, or allows it to run with an optional transform, based on the * deserialised JSON response for the request. * - * @param {Function} mockCheck function that returns true if the request should be mocked. - * @param {Object} mock A mock object to wrap in a JSON response, if the request should be mocked. + * @param {Function} mockCheck function that returns true if the request should be mocked. + * @param {Object} mock A mock object to wrap in a JSON response, if the request should be mocked. * @param {Function|undefined} responseObjectTransform An optional function that transforms the response's object before the response is used. * @return {Promise} Promise that uses `mockCheck` to see if a request should be mocked with `mock`, and optionally transforms the response with `responseObjectTransform`. */ diff --git a/packages/e2e-test-utils/src/press-key-with-modifier.js b/packages/e2e-test-utils/src/press-key-with-modifier.js index abb7f168e6090..e1e5aab425e57 100644 --- a/packages/e2e-test-utils/src/press-key-with-modifier.js +++ b/packages/e2e-test-utils/src/press-key-with-modifier.js @@ -117,7 +117,7 @@ async function emulateClipboard( type ) { * is normalized to platform-specific modifier. * * @param {string} modifier Modifier key. - * @param {string} key Key to press while modifier held. + * @param {string} key Key to press while modifier held. */ export async function pressKeyWithModifier( modifier, key ) { if ( modifier.toLowerCase() === 'primary' && key.toLowerCase() === 'a' ) { diff --git a/packages/e2e-test-utils/src/visit-admin-page.js b/packages/e2e-test-utils/src/visit-admin-page.js index 8f4a6c7260d34..81f54c4fcc65c 100644 --- a/packages/e2e-test-utils/src/visit-admin-page.js +++ b/packages/e2e-test-utils/src/visit-admin-page.js @@ -15,7 +15,7 @@ import { getPageError } from './get-page-error'; * Visits admin page; if user is not logged in then it logging in it first, then visits admin page. * * @param {string} adminPath String to be serialized as pathname. - * @param {string} query String to be serialized as query portion of URL. + * @param {string} query String to be serialized as query portion of URL. */ export async function visitAdminPage( adminPath, query ) { await page.goto( createURL( join( 'wp-admin', adminPath ), query ) ); diff --git a/packages/e2e-tests/specs/editor/plugins/annotations.test.js b/packages/e2e-tests/specs/editor/plugins/annotations.test.js index a14fa73ae8cd9..f1b90553d6dbc 100644 --- a/packages/e2e-tests/specs/editor/plugins/annotations.test.js +++ b/packages/e2e-tests/specs/editor/plugins/annotations.test.js @@ -38,7 +38,7 @@ describe( 'Using Plugins API', () => { * Annotates the text in the first block from start to end. * * @param {number} start Position to start the annotation. - * @param {number} end Position to end the annotation. + * @param {number} end Position to end the annotation. * * @return {void} */ diff --git a/packages/e2e-tests/specs/experiments/navigation.test.js b/packages/e2e-tests/specs/experiments/navigation.test.js index 7b2a81824de7a..e1207c7ed9c2c 100644 --- a/packages/e2e-tests/specs/experiments/navigation.test.js +++ b/packages/e2e-tests/specs/experiments/navigation.test.js @@ -53,7 +53,7 @@ const REST_PAGES_ROUTES = [ * routes (extressed as substrings). * * @param {string} reqUrl the full URL to be tested for matches. - * @param {Array} routes array of strings to match against the URL. + * @param {Array} routes array of strings to match against the URL. */ function matchUrlToRoute( reqUrl, routes ) { return routes.some( ( route ) => reqUrl.includes( route ) ); @@ -104,7 +104,7 @@ async function mockSearchResponse( items ) { * Note: this needs to be within a single call to * `setUpResponseMocking` as you can only setup response mocking once per test run. * - * @param {Array} menus menus to provide as mocked responses to menus entity API requests. + * @param {Array} menus menus to provide as mocked responses to menus entity API requests. * @param {Array} menuItems menu items to provide as mocked responses to menu-items entity API requests. */ async function mockAllMenusResponses( @@ -171,10 +171,10 @@ async function mockCreatePageResponse( title, slug ) { /** * Interacts with the LinkControl to perform a search and select a returned suggestion * - * @param {Object} link link object to be tested - * @param {string} link.url What will be typed in the search input + * @param {Object} link link object to be tested + * @param {string} link.url What will be typed in the search input * @param {string} link.label What the resulting label will be in the creating Link Block after the block is created. - * @param {string} link.type What kind of suggestion should be clicked, ie. 'url', 'create', or 'entity' + * @param {string} link.type What kind of suggestion should be clicked, ie. 'url', 'create', or 'entity' */ async function updateActiveNavigationLink( { url, label, type } ) { const typeClasses = { diff --git a/packages/edit-navigation/src/index.js b/packages/edit-navigation/src/index.js index 63e47f7d1589f..f10c0cd421d54 100644 --- a/packages/edit-navigation/src/index.js +++ b/packages/edit-navigation/src/index.js @@ -39,12 +39,12 @@ function disableInsertingNonNavigationBlocks( settings, name ) { * It seems like there is no suitable package to import this from. Ideally it would be either part of core-data. * Until we refactor it, just copying the code is the simplest solution. * - * @param {string} search - * @param {Object} [searchArguments] - * @param {number} [searchArguments.isInitialSuggestions] - * @param {number} [searchArguments.type] - * @param {number} [searchArguments.subtype] - * @param {Object} [editorSettings] + * @param {string} search + * @param {Object} [searchArguments] + * @param {number} [searchArguments.isInitialSuggestions] + * @param {number} [searchArguments.type] + * @param {number} [searchArguments.subtype] + * @param {Object} [editorSettings] * @param {boolean} [editorSettings.disablePostFormats=false] * @return {Promise} List of suggestions */ diff --git a/packages/edit-navigation/src/store/controls.js b/packages/edit-navigation/src/store/controls.js index fb327b8fff8fc..f704534ffcb2f 100644 --- a/packages/edit-navigation/src/store/controls.js +++ b/packages/edit-navigation/src/store/controls.js @@ -96,7 +96,7 @@ export function resolveMenuItems( menuId ) { * * @param {string} registryName Registry name. * @param {string} selectorName Selector name. - * @param {Array} args Selector arguments. + * @param {Array} args Selector arguments. * @return {Object} control descriptor. */ export function select( registryName, selectorName, ...args ) { @@ -113,7 +113,7 @@ export function select( registryName, selectorName, ...args ) { * * @param {string} registryName Registry name. * @param {string} actionName Action name. - * @param {Array} args Selector arguments. + * @param {Array} args Selector arguments. * @return {Object} control descriptor. */ export function dispatch( registryName, actionName, ...args ) { diff --git a/packages/edit-navigation/src/store/reducer.js b/packages/edit-navigation/src/store/reducer.js index 544857b159af2..ce8c4a49987b2 100644 --- a/packages/edit-navigation/src/store/reducer.js +++ b/packages/edit-navigation/src/store/reducer.js @@ -8,7 +8,7 @@ import { combineReducers } from '@wordpress/data'; * * Stores menuItemId -> clientId mapping which is necessary for saving the navigation. * - * @param {Object} state Redux state + * @param {Object} state Redux state * @param {Object} action Redux action * @return {Object} Updated state */ @@ -27,7 +27,7 @@ export function mapping( state, action ) { * Enables serializeProcessing action wrapper by storing the underlying execution * state and any pending actions. * - * @param {Object} state Redux state + * @param {Object} state Redux state * @param {Object} action Redux action * @return {Object} Updated state */ diff --git a/packages/edit-navigation/src/store/selectors.js b/packages/edit-navigation/src/store/selectors.js index 2891e1ac3046d..30b8ddc6796e7 100644 --- a/packages/edit-navigation/src/store/selectors.js +++ b/packages/edit-navigation/src/store/selectors.js @@ -58,8 +58,8 @@ export const hasResolvedNavigationPost = createRegistrySelector( /** * Returns a menu item represented by the block with id clientId. * - * @param {number} postId Navigation post id - * @param {number} clientId Block clientId + * @param {number} postId Navigation post id + * @param {number} clientId Block clientId * @return {Object|null} Menu item entity */ export const getMenuItemForClientId = createRegistrySelector( diff --git a/packages/edit-post/src/components/block-settings-menu/plugin-block-settings-menu-item.js b/packages/edit-post/src/components/block-settings-menu/plugin-block-settings-menu-item.js index 9c2f68e02fd76..43bf45cea9f4d 100644 --- a/packages/edit-post/src/components/block-settings-menu/plugin-block-settings-menu-item.js +++ b/packages/edit-post/src/components/block-settings-menu/plugin-block-settings-menu-item.js @@ -22,7 +22,7 @@ const isEverySelectedBlockAllowed = ( selected, allowed ) => * is of one allowed type (not necessarily the same). * * @param {string[]} selectedBlocks Array containing the names of the blocks selected - * @param {string[]} allowedBlocks Array containing the names of the blocks allowed + * @param {string[]} allowedBlocks Array containing the names of the blocks allowed * @return {boolean} Whether the item will be rendered or not. */ const shouldRenderItem = ( selectedBlocks, allowedBlocks ) => diff --git a/packages/edit-post/src/components/browser-url/index.js b/packages/edit-post/src/components/browser-url/index.js index d4cbd7f867706..1212f9b580c8a 100644 --- a/packages/edit-post/src/components/browser-url/index.js +++ b/packages/edit-post/src/components/browser-url/index.js @@ -19,7 +19,7 @@ export function getPostEditURL( postId ) { /** * Returns the Post's Trashed URL. * - * @param {number} postId Post ID. + * @param {number} postId Post ID. * @param {string} postType Post Type. * * @return {string} Post trashed URL. @@ -63,8 +63,8 @@ export class BrowserURL extends Component { /** * Navigates the browser to the post trashed URL to show a notice about the trashed post. * - * @param {number} postId Post ID. - * @param {string} postType Post Type. + * @param {number} postId Post ID. + * @param {string} postType Post Type. */ setTrashURL( postId, postType ) { window.location.href = getPostTrashedURL( postId, postType ); diff --git a/packages/edit-post/src/components/editor-initialization/index.js b/packages/edit-post/src/components/editor-initialization/index.js index adebea3f45497..0ba9cc863f473 100644 --- a/packages/edit-post/src/components/editor-initialization/index.js +++ b/packages/edit-post/src/components/editor-initialization/index.js @@ -10,7 +10,7 @@ import { * Data component used for initializing the editor and re-initializes * when postId changes or on unmount. * - * @param {number} postId The id of the post. + * @param {number} postId The id of the post. * @return {null} This is a data component so does not render any ui. */ export default function EditorInitialization( { postId } ) { diff --git a/packages/edit-post/src/components/editor-initialization/listener-hooks.js b/packages/edit-post/src/components/editor-initialization/listener-hooks.js index 91af99219220d..48e68c36b1ede 100644 --- a/packages/edit-post/src/components/editor-initialization/listener-hooks.js +++ b/packages/edit-post/src/components/editor-initialization/listener-hooks.js @@ -17,7 +17,7 @@ import { * This listener hook monitors for block selection and triggers the appropriate * sidebar state. * - * @param {number} postId The current post id. + * @param {number} postId The current post id. */ export const useBlockSelectionListener = ( postId ) => { const { hasBlockSelection, isEditorSidebarOpened } = useSelect( diff --git a/packages/edit-post/src/components/editor-initialization/utils.js b/packages/edit-post/src/components/editor-initialization/utils.js index 11935236c8344..d86f4149016e7 100644 --- a/packages/edit-post/src/components/editor-initialization/utils.js +++ b/packages/edit-post/src/components/editor-initialization/utils.js @@ -2,9 +2,9 @@ * Given a selector returns a functions that returns the listener only * if the returned value from the selector changes. * - * @param {Function} selector Selector. - * @param {Function} listener Listener. - * @param {boolean} initial Flags whether listener should be invoked on + * @param {Function} selector Selector. + * @param {Function} listener Listener. + * @param {boolean} initial Flags whether listener should be invoked on * initial call. * @return {Function} Listener creator. */ diff --git a/packages/edit-post/src/components/header/plugin-more-menu-item/index.js b/packages/edit-post/src/components/header/plugin-more-menu-item/index.js index 2d55772447885..5bdc188205059 100644 --- a/packages/edit-post/src/components/header/plugin-more-menu-item/index.js +++ b/packages/edit-post/src/components/header/plugin-more-menu-item/index.js @@ -9,11 +9,11 @@ import { withPluginContext } from '@wordpress/plugins'; * Renders a menu item in `Plugins` group in `More Menu` drop down, and can be used to as a button or link depending on the props provided. * The text within the component appears as the menu item label. * - * @param {Object} props Component properties. - * @param {string} [props.href] When `href` is provided then the menu item is represented as an anchor rather than button. It corresponds to the `href` attribute of the anchor. + * @param {Object} props Component properties. + * @param {string} [props.href] When `href` is provided then the menu item is represented as an anchor rather than button. It corresponds to the `href` attribute of the anchor. * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. - * @param {Function} [props.onClick=noop] The callback function to be executed when the user clicks the menu item. - * @param {...*} [props.other] Any additional props are passed through to the underlying [MenuItem](/packages/components/src/menu-item/README.md) component. + * @param {Function} [props.onClick=noop] The callback function to be executed when the user clicks the menu item. + * @param {...*} [props.other] Any additional props are passed through to the underlying [MenuItem](/packages/components/src/menu-item/README.md) component. * * @example * ES5 diff --git a/packages/edit-post/src/components/header/plugin-sidebar-more-menu-item/index.js b/packages/edit-post/src/components/header/plugin-sidebar-more-menu-item/index.js index 2ed29f7f8d8c3..2c3426c231802 100644 --- a/packages/edit-post/src/components/header/plugin-sidebar-more-menu-item/index.js +++ b/packages/edit-post/src/components/header/plugin-sidebar-more-menu-item/index.js @@ -8,8 +8,8 @@ import { ComplementaryAreaMoreMenuItem } from '@wordpress/interface'; * and can be used to activate the corresponding `PluginSidebar` component. * The text within the component appears as the menu item label. * - * @param {Object} props Component props. - * @param {string} props.target A string identifying the target sidebar you wish to be activated by this menu item. Must be the same as the `name` prop you have given to that sidebar. + * @param {Object} props Component props. + * @param {string} props.target A string identifying the target sidebar you wish to be activated by this menu item. Must be the same as the `name` prop you have given to that sidebar. * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. * * @example diff --git a/packages/edit-post/src/components/sidebar/plugin-document-setting-panel/index.js b/packages/edit-post/src/components/sidebar/plugin-document-setting-panel/index.js index 9f036edee62c7..72b9e2d364c87 100644 --- a/packages/edit-post/src/components/sidebar/plugin-document-setting-panel/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-document-setting-panel/index.js @@ -54,10 +54,10 @@ const PluginDocumentSettingFill = ( { /** * Renders items below the Status & Availability panel in the Document Sidebar. * - * @param {Object} props Component properties. - * @param {string} [props.name] The machine-friendly name for the panel. - * @param {string} [props.className] An optional class name added to the row. - * @param {string} [props.title] The title of the panel + * @param {Object} props Component properties. + * @param {string} [props.name] The machine-friendly name for the panel. + * @param {string} [props.className] An optional class name added to the row. + * @param {string} [props.title] The title of the panel * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. * * @example diff --git a/packages/edit-post/src/components/sidebar/plugin-post-publish-panel/index.js b/packages/edit-post/src/components/sidebar/plugin-post-publish-panel/index.js index 5a54525cf5ca2..603ac9838669c 100644 --- a/packages/edit-post/src/components/sidebar/plugin-post-publish-panel/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-post-publish-panel/index.js @@ -29,11 +29,11 @@ const PluginPostPublishPanelFill = ( { * Renders provided content to the post-publish panel in the publish flow * (side panel that opens after a user publishes the post). * - * @param {Object} props Component properties. - * @param {string} [props.className] An optional class name added to the panel. - * @param {string} [props.title] Title displayed at the top of the panel. - * @param {boolean} [props.initialOpen=false] Whether to have the panel initially opened. When no title is provided it is always opened. - * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. + * @param {Object} props Component properties. + * @param {string} [props.className] An optional class name added to the panel. + * @param {string} [props.title] Title displayed at the top of the panel. + * @param {boolean} [props.initialOpen=false] Whether to have the panel initially opened. When no title is provided it is always opened. + * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. * * @example * ES5 diff --git a/packages/edit-post/src/components/sidebar/plugin-pre-publish-panel/index.js b/packages/edit-post/src/components/sidebar/plugin-pre-publish-panel/index.js index 7eedb60103ba4..721f031664dac 100644 --- a/packages/edit-post/src/components/sidebar/plugin-pre-publish-panel/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-pre-publish-panel/index.js @@ -29,12 +29,12 @@ const PluginPrePublishPanelFill = ( { * Renders provided content to the pre-publish side panel in the publish flow * (side panel that opens when a user first pushes "Publish" from the main editor). * - * @param {Object} props Component props. - * @param {string} [props.className] An optional class name added to the panel. - * @param {string} [props.title] Title displayed at the top of the panel. - * @param {boolean} [props.initialOpen=false] Whether to have the panel initially opened. + * @param {Object} props Component props. + * @param {string} [props.className] An optional class name added to the panel. + * @param {string} [props.title] Title displayed at the top of the panel. + * @param {boolean} [props.initialOpen=false] Whether to have the panel initially opened. * When no title is provided it is always opened. - * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) + * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) * icon slug string, or an SVG WP element, to be rendered when * the sidebar is pinned to toolbar. * diff --git a/packages/edit-post/src/components/sidebar/plugin-sidebar/index.js b/packages/edit-post/src/components/sidebar/plugin-sidebar/index.js index 27a1d7733f1b8..984ea29ef19da 100644 --- a/packages/edit-post/src/components/sidebar/plugin-sidebar/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-sidebar/index.js @@ -15,12 +15,12 @@ import { __ } from '@wordpress/i18n'; * * @see PluginSidebarMoreMenuItem * - * @param {Object} props Element props. - * @param {string} props.name A string identifying the sidebar. Must be unique for every sidebar registered within the scope of your plugin. - * @param {string} [props.className] An optional class name added to the sidebar body. - * @param {string} props.title Title displayed at the top of the sidebar. - * @param {boolean} [props.isPinnable=true] Whether to allow to pin sidebar to toolbar. - * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. + * @param {Object} props Element props. + * @param {string} props.name A string identifying the sidebar. Must be unique for every sidebar registered within the scope of your plugin. + * @param {string} [props.className] An optional class name added to the sidebar body. + * @param {string} props.title Title displayed at the top of the sidebar. + * @param {boolean} [props.isPinnable=true] Whether to allow to pin sidebar to toolbar. + * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. * * @example * ES5 diff --git a/packages/edit-post/src/index.native.js b/packages/edit-post/src/index.native.js index 8aa2057b6c32e..5d23d973cf776 100644 --- a/packages/edit-post/src/index.native.js +++ b/packages/edit-post/src/index.native.js @@ -20,9 +20,9 @@ let editorInitialized = false; * Initializes the Editor and returns a componentProvider * that can be registered with `AppRegistry.registerComponent` * - * @param {string} id Unique identifier for editor instance. - * @param {Object} postType Post type of the post to edit. - * @param {Object} postId ID of the post to edit (unused right now) + * @param {string} id Unique identifier for editor instance. + * @param {Object} postType Post type of the post to edit. + * @param {Object} postId ID of the post to edit (unused right now) */ export function initializeEditor( id, postType, postId ) { if ( editorInitialized ) { diff --git a/packages/edit-post/src/store/controls.js b/packages/edit-post/src/store/controls.js index 3a64e045f6966..f097aafb9a8e2 100644 --- a/packages/edit-post/src/store/controls.js +++ b/packages/edit-post/src/store/controls.js @@ -8,7 +8,7 @@ import { createRegistryControl } from '@wordpress/data'; * * @param {string} storeName Store name. * @param {string} selectorName Selector name. - * @param {Array} args Selector arguments. + * @param {Array} args Selector arguments. * * @return {Object} control descriptor. */ diff --git a/packages/edit-post/src/store/reducer.js b/packages/edit-post/src/store/reducer.js index 934de97aa73c0..f037575f12f7b 100644 --- a/packages/edit-post/src/store/reducer.js +++ b/packages/edit-post/src/store/reducer.js @@ -188,8 +188,8 @@ export function publishSidebarActive( state = false, action ) { * A "true" value means the meta boxes saving request is in-flight. * * - * @param {boolean} state Previous state. - * @param {Object} action Action Object. + * @param {boolean} state Previous state. + * @param {Object} action Action Object. * * @return {Object} Updated state. */ @@ -207,8 +207,8 @@ export function isSavingMetaBoxes( state = false, action ) { /** * Reducer keeping track of the meta boxes per location. * - * @param {boolean} state Previous state. - * @param {Object} action Action Object. + * @param {boolean} state Previous state. + * @param {Object} action Action Object. * * @return {Object} Updated state. */ diff --git a/packages/edit-post/src/store/selectors.js b/packages/edit-post/src/store/selectors.js index 68dcc83671ed0..522e6fedbbfea 100644 --- a/packages/edit-post/src/store/selectors.js +++ b/packages/edit-post/src/store/selectors.js @@ -153,8 +153,8 @@ export function isEditorPanelEnabled( state, panelName ) { * Returns true if the given panel is open, or false otherwise. Panels are * closed by default. * - * @param {Object} state Global application state. - * @param {string} panelName A string that identifies the panel. + * @param {Object} state Global application state. + * @param {string} panelName A string that identifies the panel. * * @return {boolean} Whether or not the panel is open. */ @@ -169,8 +169,8 @@ export function isEditorPanelOpened( state, panelName ) { /** * Returns true if a modal is active, or false otherwise. * - * @param {Object} state Global application state. - * @param {string} modalName A string that uniquely identifies the modal. + * @param {Object} state Global application state. + * @param {string} modalName A string that uniquely identifies the modal. * * @return {boolean} Whether the modal is active. */ @@ -194,8 +194,8 @@ export function isFeatureActive( state, feature ) { * Returns true if the plugin item is pinned to the header. * When the value is not set it defaults to true. * - * @param {Object} state Global application state. - * @param {string} pluginName Plugin item name. + * @param {Object} state Global application state. + * @param {string} pluginName Plugin item name. * * @return {boolean} Whether the plugin item is pinned. */ @@ -284,7 +284,7 @@ export const getAllMetaBoxes = createSelector( /** * Returns true if the post is using Meta Boxes * - * @param {Object} state Global application state + * @param {Object} state Global application state * * @return {boolean} Whether there are metaboxes or not. */ @@ -295,7 +295,7 @@ export function hasMetaBoxes( state ) { /** * Returns true if the Meta Boxes are being saved. * - * @param {Object} state Global application state. + * @param {Object} state Global application state. * * @return {boolean} Whether the metaboxes are being saved. */ @@ -317,7 +317,7 @@ export function __experimentalGetPreviewDeviceType( state ) { /** * Returns true if the inserter is opened. * - * @param {Object} state Global application state. + * @param {Object} state Global application state. * * @return {boolean} Whether the inserter is opened. */ diff --git a/packages/edit-post/src/utils/meta-boxes.js b/packages/edit-post/src/utils/meta-boxes.js index a781b96318402..f2c9fa00a7947 100644 --- a/packages/edit-post/src/utils/meta-boxes.js +++ b/packages/edit-post/src/utils/meta-boxes.js @@ -3,7 +3,7 @@ * whether the meta box area is opened or not. * If the MetaBox Area is visible returns it, and returns the original container instead. * - * @param {string} location Meta Box location. + * @param {string} location Meta Box location. * @return {string} HTML content. */ export const getMetaBoxContainer = ( location ) => { diff --git a/packages/edit-site/src/components/editor/global-styles-renderer.js b/packages/edit-site/src/components/editor/global-styles-renderer.js index 1af357df367e9..5d067eff3f96d 100644 --- a/packages/edit-site/src/components/editor/global-styles-renderer.js +++ b/packages/edit-site/src/components/editor/global-styles-renderer.js @@ -51,7 +51,7 @@ export default ( blockData, baseTree, userTree ) => { * Transform given style tree into a set of style declarations. * * @param {Object} blockSupports What styles the block supports. - * @param {Object} blockStyles Block styles. + * @param {Object} blockStyles Block styles. * * @return {Array} An array of style declarations. */ diff --git a/packages/edit-site/src/store/actions.js b/packages/edit-site/src/store/actions.js index 9785b46a5ddbe..4c407b6dc1df4 100644 --- a/packages/edit-site/src/store/actions.js +++ b/packages/edit-site/src/store/actions.js @@ -118,11 +118,11 @@ export function setHomeTemplateId( homeTemplateId ) { /** * Resolves the template for a page and displays both. * - * @param {Object} page The page object. - * @param {string} page.type The page type. - * @param {string} page.slug The page slug. - * @param {string} page.path The page path. - * @param {Object} page.context The page context. + * @param {Object} page The page object. + * @param {string} page.type The page type. + * @param {string} page.slug The page slug. + * @param {string} page.path The page path. + * @param {Object} page.context The page context. * * @return {number} The resolved template ID for the page route. */ diff --git a/packages/edit-site/src/store/reducer.js b/packages/edit-site/src/store/reducer.js index a079efb6a4d55..86864df1934c7 100644 --- a/packages/edit-site/src/store/reducer.js +++ b/packages/edit-site/src/store/reducer.js @@ -28,7 +28,7 @@ const createWithInitialState = ( initialState ) => ( reducer ) => { /** * Reducer returning the user preferences. * - * @param {Object} state Current state. + * @param {Object} state Current state. * * @return {Object} Updated state. */ @@ -160,7 +160,7 @@ export function page( state, action ) { /** * Reducer for information about the site's homepage. * - * @param {Object} state Current state. + * @param {Object} state Current state. * @param {Object} action Dispatched action. * * @return {Object} Updated state. diff --git a/packages/edit-site/src/utils/find-template.js b/packages/edit-site/src/utils/find-template.js index 83e2d984ceb6a..ed6c4e2268c91 100644 --- a/packages/edit-site/src/utils/find-template.js +++ b/packages/edit-site/src/utils/find-template.js @@ -11,7 +11,7 @@ const { fetch } = window; /** * Find the template for a given page path. * - * @param {string} path The page path. + * @param {string} path The page path. * @param {Function} getEntityRecords The promise-returning `getEntityRecords` selector to use. * * @return {number} The found template ID. diff --git a/packages/edit-widgets/src/store/actions.js b/packages/edit-widgets/src/store/actions.js index 5d000f5ac3f23..a3c899e10eeed 100644 --- a/packages/edit-widgets/src/store/actions.js +++ b/packages/edit-widgets/src/store/actions.js @@ -113,8 +113,8 @@ export function* saveWidgetAreas( widgetAreas ) { /** * Sets the clientId stored for a particular widgetId. * - * @param {number} clientId Client id. - * @param {number} widgetId Widget id. + * @param {number} clientId Client id. + * @param {number} widgetId Widget id. * @return {Object} Action. */ export function setWidgetIdForClientId( clientId, widgetId ) { diff --git a/packages/edit-widgets/src/store/controls.js b/packages/edit-widgets/src/store/controls.js index 1b836b5be1aaf..81f4cc6944274 100644 --- a/packages/edit-widgets/src/store/controls.js +++ b/packages/edit-widgets/src/store/controls.js @@ -93,7 +93,7 @@ export function resolveWidgetAreas( query = buildWidgetAreasQuery() ) { * * @param {string} registryName Registry name. * @param {string} selectorName Selector name. - * @param {Array} args Selector arguments. + * @param {Array} args Selector arguments. * @return {Object} control descriptor. */ export function select( registryName, selectorName, ...args ) { @@ -110,7 +110,7 @@ export function select( registryName, selectorName, ...args ) { * * @param {string} registryName Registry name. * @param {string} actionName Action name. - * @param {Array} args Selector arguments. + * @param {Array} args Selector arguments. * @return {Object} control descriptor. */ export function dispatch( registryName, actionName, ...args ) { diff --git a/packages/edit-widgets/src/store/reducer.js b/packages/edit-widgets/src/store/reducer.js index f24805d59d41d..731a2ce1a7cd1 100644 --- a/packages/edit-widgets/src/store/reducer.js +++ b/packages/edit-widgets/src/store/reducer.js @@ -8,7 +8,7 @@ import { combineReducers } from '@wordpress/data'; * * Stores widgetId -> clientId mapping which is necessary for saving the navigation. * - * @param {Object} state Redux state + * @param {Object} state Redux state * @param {Object} action Redux action * @return {Object} Updated state */ diff --git a/packages/edit-widgets/src/store/selectors.js b/packages/edit-widgets/src/store/selectors.js index 3fb8af255849c..796617c340a9e 100644 --- a/packages/edit-widgets/src/store/selectors.js +++ b/packages/edit-widgets/src/store/selectors.js @@ -31,7 +31,7 @@ export const getWidgets = createRegistrySelector( ( select ) => () => { /** * Returns API widget data for a particular widget ID. * - * @param {number} id Widget ID + * @param {number} id Widget ID * @return {Object} API widget data for a particular widget ID. */ export const getWidget = createRegistrySelector( diff --git a/packages/editor/src/components/post-publish-panel/postpublish.js b/packages/editor/src/components/post-publish-panel/postpublish.js index c7aa69bddb20c..1b720f7155644 100644 --- a/packages/editor/src/components/post-publish-panel/postpublish.js +++ b/packages/editor/src/components/post-publish-panel/postpublish.js @@ -28,7 +28,7 @@ const POSTNAME = '%postname%'; /** * Returns URL for a future post. * - * @param {Object} post Post object. + * @param {Object} post Post object. * * @return {string} PostPublish URL. */ diff --git a/packages/editor/src/components/post-saved-state/index.js b/packages/editor/src/components/post-saved-state/index.js index bc98454a9767e..fb6e6d15fead8 100644 --- a/packages/editor/src/components/post-saved-state/index.js +++ b/packages/editor/src/components/post-saved-state/index.js @@ -23,10 +23,10 @@ import PostSwitchToDraftButton from '../post-switch-to-draft-button'; * Component showing whether the post is saved or not and providing save * buttons. * - * @param {Object} props Component props. - * @param {?boolean} props.forceIsDirty Whether to force the post to be marked + * @param {Object} props Component props. + * @param {?boolean} props.forceIsDirty Whether to force the post to be marked * as dirty. - * @param {?boolean} props.forceIsSaving Whether to force the post to be marked + * @param {?boolean} props.forceIsSaving Whether to force the post to be marked * as being saved. * @param {?boolean} props.showIconLabels Whether interface buttons show labels instead of icons * @return {import('@wordpress/element').WPComponent} The component. @@ -73,8 +73,7 @@ export default function PostSavedState( { isSaveable: isEditedPostSaveable(), isScheduled: isCurrentPostScheduled(), hasPublishAction: - getCurrentPost()?.[ '_links' ]?.[ 'wp:action-publish' ] ?? - false, + getCurrentPost()?._links?.[ 'wp:action-publish' ] ?? false, }; }, [ forceIsDirty, forceIsSaving ] diff --git a/packages/editor/src/components/post-type-support-check/index.js b/packages/editor/src/components/post-type-support-check/index.js index 7aae5e6abb036..8899aac652c25 100644 --- a/packages/editor/src/components/post-type-support-check/index.js +++ b/packages/editor/src/components/post-type-support-check/index.js @@ -12,11 +12,11 @@ import { withSelect } from '@wordpress/data'; * A component which renders its own children only if the current editor post * type supports one of the given `supportKeys` prop. * - * @param {Object} props Props. - * @param {string} [props.postType] Current post type. - * @param {WPElement} props.children Children to be rendered if post + * @param {Object} props Props. + * @param {string} [props.postType] Current post type. + * @param {WPElement} props.children Children to be rendered if post * type supports. - * @param {(string|string[])} props.supportKeys String or string array of keys + * @param {(string|string[])} props.supportKeys String or string array of keys * to test. * * @return {WPComponent} The component to be rendered. diff --git a/packages/editor/src/components/provider/index.js b/packages/editor/src/components/provider/index.js index 4195ee2cb85d6..ca91426d542e4 100644 --- a/packages/editor/src/components/provider/index.js +++ b/packages/editor/src/components/provider/index.js @@ -37,12 +37,12 @@ import ConvertToGroupButtons from '../convert-to-group-buttons'; * It seems like there is no suitable package to import this from. Ideally it would be either part of core-data. * Until we refactor it, just copying the code is the simplest solution. * - * @param {string} search - * @param {Object} [searchArguments] - * @param {number} [searchArguments.isInitialSuggestions] - * @param {number} [searchArguments.type] - * @param {number} [searchArguments.subtype] - * @param {Object} [editorSettings] + * @param {string} search + * @param {Object} [searchArguments] + * @param {number} [searchArguments.isInitialSuggestions] + * @param {number} [searchArguments.type] + * @param {number} [searchArguments.subtype] + * @param {Object} [editorSettings] * @param {boolean} [editorSettings.disablePostFormats=false] * @return {Promise} List of suggestions */ diff --git a/packages/editor/src/store/actions.js b/packages/editor/src/store/actions.js index 89e213f79754d..a4fe1c3e7a84d 100644 --- a/packages/editor/src/store/actions.js +++ b/packages/editor/src/store/actions.js @@ -34,9 +34,9 @@ import serializeBlocks from './utils/serialize-blocks'; * Returns an action generator used in signalling that editor has initialized with * the specified post object and editor settings. * - * @param {Object} post Post object. - * @param {Object} edits Initial edited attributes object. - * @param {Array?} template Block Template. + * @param {Object} post Post object. + * @param {Object} edits Initial edited attributes object. + * @param {Array?} template Block Template. */ export function* setupEditor( post, edits, template ) { // In order to ensure maximum of a single parse during setup, edits are @@ -175,7 +175,7 @@ export function updatePost( edits ) { * Returns an action object used to setup the editor state when first opening * an editor. * - * @param {Object} post Post object. + * @param {Object} post Post object. * * @return {Object} Action object. */ @@ -212,7 +212,7 @@ export function* editPost( edits, options ) { * Returns action object produced by the updatePost creator augmented by * an optimist option that signals optimistically applying updates. * - * @param {Object} edits Updated post fields. + * @param {Object} edits Updated post fields. * * @return {Object} Action object. */ @@ -406,7 +406,7 @@ export function createUndoLevel() { /** * Returns an action object used to lock the editor. * - * @param {Object} lock Details about the post lock status, user, and nonce. + * @param {Object} lock Details about the post lock status, user, and nonce. * * @return {Object} Action object. */ @@ -553,7 +553,7 @@ export function disablePublishSidebar() { /** * Returns an action object used to signal that post saving is locked. * - * @param {string} lockName The lock name. + * @param {string} lockName The lock name. * * @example * ``` @@ -603,7 +603,7 @@ export function lockPostSaving( lockName ) { /** * Returns an action object used to signal that post saving is unlocked. * - * @param {string} lockName The lock name. + * @param {string} lockName The lock name. * * @example * ``` @@ -623,7 +623,7 @@ export function unlockPostSaving( lockName ) { /** * Returns an action object used to signal that post autosaving is locked. * - * @param {string} lockName The lock name. + * @param {string} lockName The lock name. * * @example * ``` @@ -643,7 +643,7 @@ export function lockPostAutosaving( lockName ) { /** * Returns an action object used to signal that post autosaving is unlocked. * - * @param {string} lockName The lock name. + * @param {string} lockName The lock name. * * @example * ``` diff --git a/packages/editor/src/store/controls.js b/packages/editor/src/store/controls.js index c21fed5211062..939e70a5b7edf 100644 --- a/packages/editor/src/store/controls.js +++ b/packages/editor/src/store/controls.js @@ -32,8 +32,8 @@ export function getRegistry() { * * @see https://github.com/WordPress/wordpress-develop/blob/6dad32d2aed47e6c0cf2aee8410645f6d7aba6bd/src/wp-login.php#L103 * - * @param {string} postId Post ID. - * @param {boolean} isPostNew Whether post new. + * @param {string} postId Post ID. + * @param {boolean} isPostNew Whether post new. * @return {string} sessionStorage key */ function postKey( postId, isPostNew ) { diff --git a/packages/editor/src/store/effects/reusable-blocks.js b/packages/editor/src/store/effects/reusable-blocks.js index 4cef632d7c0ba..348fe8de4c1ae 100644 --- a/packages/editor/src/store/effects/reusable-blocks.js +++ b/packages/editor/src/store/effects/reusable-blocks.js @@ -37,8 +37,8 @@ const REUSABLE_BLOCK_NOTICE_ID = 'REUSABLE_BLOCK_NOTICE_ID'; /** * Fetch Reusable blocks Effect Handler. * - * @param {Object} action action object. - * @param {Object} store Redux Store. + * @param {Object} action action object. + * @param {Object} store Redux Store. */ export const fetchReusableBlocks = async ( action, store ) => { const { id } = action; @@ -100,8 +100,8 @@ export const fetchReusableBlocks = async ( action, store ) => { /** * Save Reusable blocks Effect Handler. * - * @param {Object} action action object. - * @param {Object} store Redux Store. + * @param {Object} action action object. + * @param {Object} store Redux Store. */ export const saveReusableBlocks = async ( action, store ) => { // TODO: these are potentially undefined, this fix is in place @@ -154,8 +154,8 @@ export const saveReusableBlocks = async ( action, store ) => { /** * Delete Reusable blocks Effect Handler. * - * @param {Object} action action object. - * @param {Object} store Redux Store. + * @param {Object} action action object. + * @param {Object} store Redux Store. */ export const deleteReusableBlocks = async ( action, store ) => { // TODO: these are potentially undefined, this fix is in place @@ -227,8 +227,8 @@ export const deleteReusableBlocks = async ( action, store ) => { /** * Convert a reusable block to a static block effect handler * - * @param {Object} action action object. - * @param {Object} store Redux Store. + * @param {Object} action action object. + * @param {Object} store Redux Store. */ export const convertBlockToStatic = ( action, store ) => { const state = store.getState(); @@ -244,8 +244,8 @@ export const convertBlockToStatic = ( action, store ) => { /** * Convert a static block to a reusable block effect handler * - * @param {Object} action action object. - * @param {Object} store Redux Store. + * @param {Object} action action object. + * @param {Object} store Redux Store. */ export const convertBlockToReusable = ( action, store ) => { const { dispatch } = store; diff --git a/packages/editor/src/store/reducer.js b/packages/editor/src/store/reducer.js index 9fd9c910360d3..501c038ef492d 100644 --- a/packages/editor/src/store/reducer.js +++ b/packages/editor/src/store/reducer.js @@ -127,8 +127,8 @@ export function template( state = { isValid: true }, action ) { /** * Reducer returning the user preferences. * - * @param {Object} state Current state. - * @param {Object} action Dispatched action. + * @param {Object} state Current state. + * @param {Object} action Dispatched action. * * @return {string} Updated state. */ @@ -177,7 +177,7 @@ export function saving( state = {}, action ) { * * @typedef {Object} PostLockState * - * @property {boolean} isLocked Whether the post is locked. + * @property {boolean} isLocked Whether the post is locked. * @property {?boolean} isTakeover Whether the post editing has been taken over. * @property {?boolean} activePostLock Active post lock value. * @property {?Object} user User that took over the post. @@ -187,7 +187,7 @@ export function saving( state = {}, action ) { * Reducer returning the post lock status. * * @param {PostLockState} state Current state. - * @param {Object} action Dispatched action. + * @param {Object} action Dispatched action. * * @return {PostLockState} Updated state. */ @@ -339,7 +339,7 @@ export const reusableBlocks = combineReducers( { * the post object is loaded properly and the initial blocks parsed. * * @param {boolean} state - * @param {Object} action + * @param {Object} action * * @return {boolean} Updated state. */ diff --git a/packages/editor/src/store/reducer.native.js b/packages/editor/src/store/reducer.native.js index 8aa3ddda38dad..7496c61996afa 100644 --- a/packages/editor/src/store/reducer.native.js +++ b/packages/editor/src/store/reducer.native.js @@ -33,8 +33,8 @@ export * from './reducer.js'; /** * Reducer returning the post title state. * - * @param {Object} state Current state. - * @param {Object} action Dispatched action. + * @param {Object} state Current state. + * @param {Object} action Dispatched action. * * @return {Object} Updated state. */ @@ -52,8 +52,8 @@ export const postTitle = combineReducers( { /** * Reducer returning the clipboard state. * - * @param {Object} state Current state. - * @param {Object} action Dispatched action. + * @param {Object} state Current state. + * @param {Object} action Dispatched action. * * @return {Object} Updated state. */ @@ -69,8 +69,8 @@ export function clipboard( state = null, action ) { /** * Reducer returning the notices state. * - * @param {Object} state Current state. - * @param {Object} action Dispatched action. + * @param {Object} state Current state. + * @param {Object} action Dispatched action. * * @return {Object} Updated state. */ diff --git a/packages/editor/src/utils/media-upload/index.js b/packages/editor/src/utils/media-upload/index.js index cbbe259642122..32f4051581336 100644 --- a/packages/editor/src/utils/media-upload/index.js +++ b/packages/editor/src/utils/media-upload/index.js @@ -13,13 +13,13 @@ import { uploadMedia } from '@wordpress/media-utils'; * Upload a media file when the file upload button is activated. * Wrapper around mediaUpload() that injects the current post ID. * - * @param {Object} $0 Parameters object passed to the function. - * @param {?Object} $0.additionalData Additional data to include in the request. - * @param {string} $0.allowedTypes Array with the types of media that can be uploaded, if unset all types are allowed. - * @param {Array} $0.filesList List of files. - * @param {?number} $0.maxUploadFileSize Maximum upload size in bytes allowed for the site. - * @param {Function} $0.onError Function called when an error happens. - * @param {Function} $0.onFileChange Function called each time a file or a temporary representation of the file is available. + * @param {Object} $0 Parameters object passed to the function. + * @param {?Object} $0.additionalData Additional data to include in the request. + * @param {string} $0.allowedTypes Array with the types of media that can be uploaded, if unset all types are allowed. + * @param {Array} $0.filesList List of files. + * @param {?number} $0.maxUploadFileSize Maximum upload size in bytes allowed for the site. + * @param {Function} $0.onError Function called when an error happens. + * @param {Function} $0.onFileChange Function called each time a file or a temporary representation of the file is available. */ export default function mediaUpload( { additionalData = {}, diff --git a/packages/editor/src/utils/terms.js b/packages/editor/src/utils/terms.js index 60cfdd8563d0b..6405cf5d1ba5b 100644 --- a/packages/editor/src/utils/terms.js +++ b/packages/editor/src/utils/terms.js @@ -6,7 +6,7 @@ import { groupBy } from 'lodash'; /** * Returns terms in a tree form. * - * @param {Array} flatTerms Array of terms in flat format. + * @param {Array} flatTerms Array of terms in flat format. * * @return {Array} Array of terms in tree format. */ diff --git a/packages/element/src/create-interpolate-element.js b/packages/element/src/create-interpolate-element.js index d3da32354bb11..21881d54ab3ce 100644 --- a/packages/element/src/create-interpolate-element.js +++ b/packages/element/src/create-interpolate-element.js @@ -29,17 +29,17 @@ const tokenizer = /<(\/)?(\w+)\s*(\/)?>/g; * * @typedef Frame * - * @property {WPElement} element A parent element which may still have - * @property {number} tokenStart Offset at which parent element first + * @property {WPElement} element A parent element which may still have + * @property {number} tokenStart Offset at which parent element first * appears. - * @property {number} tokenLength Length of string marking start of parent + * @property {number} tokenLength Length of string marking start of parent * element. - * @property {number} [prevOffset] Running offset at which parsing should + * @property {number} [prevOffset] Running offset at which parsing should * continue. - * @property {number} [leadingTextStart] Offset at which last closing element + * @property {number} [leadingTextStart] Offset at which last closing element * finished, used for finding text between * elements. - * @property {WPElement[]} children Children. + * @property {WPElement[]} children Children. */ /** @@ -101,8 +101,8 @@ function createFrame( * } * ``` * - * @param {string} interpolatedString The interpolation string to be parsed. - * @param {Object} conversionMap The map used to convert the string to + * @param {string} interpolatedString The interpolation string to be parsed. + * @param {Object} conversionMap The map used to convert the string to * a react element. * @throws {TypeError} * @return {WPElement} A wp element. @@ -134,7 +134,7 @@ const createInterpolateElement = ( interpolatedString, conversionMap ) => { * * @private * - * @param {Object} conversionMap The map being validated. + * @param {Object} conversionMap The map being validated. * * @return {boolean} True means the map is valid. */ @@ -293,7 +293,7 @@ function addText() { * * @private * - * @param {Frame} frame The Frame containing the child element and it's + * @param {Frame} frame The Frame containing the child element and it's * token information. */ function addChild( frame ) { diff --git a/packages/element/src/react-platform.js b/packages/element/src/react-platform.js index fe3d3e94a9994..af101bcf438e9 100644 --- a/packages/element/src/react-platform.js +++ b/packages/element/src/react-platform.js @@ -13,9 +13,9 @@ import { * * @see https://github.com/facebook/react/issues/10309#issuecomment-318433235 * - * @param {import('./react').WPElement} child Any renderable child, such as an element, + * @param {import('./react').WPElement} child Any renderable child, such as an element, * string, or fragment. - * @param {HTMLElement} container DOM node into which element should be rendered. + * @param {HTMLElement} container DOM node into which element should be rendered. */ export { createPortal }; @@ -29,8 +29,8 @@ export { findDOMNode }; /** * Renders a given element into the target DOM node. * - * @param {import('./react').WPElement} element Element to render. - * @param {HTMLElement} target DOM node into which element should be rendered. + * @param {import('./react').WPElement} element Element to render. + * @param {HTMLElement} target DOM node into which element should be rendered. */ export { render }; diff --git a/packages/element/src/react-platform.native.js b/packages/element/src/react-platform.native.js index fd4db1139156f..53ab257078cf6 100644 --- a/packages/element/src/react-platform.native.js +++ b/packages/element/src/react-platform.native.js @@ -34,6 +34,6 @@ const render = ( element, id ) => * Render a given element on Native. * This actually returns a componentProvider that can be registered with `AppRegistry.registerComponent` * - * @param {WPElement} element Element to render. + * @param {WPElement} element Element to render. */ export { render }; diff --git a/packages/env/lib/build-docker-compose-config.js b/packages/env/lib/build-docker-compose-config.js index 54e047fcaff9b..b96286ae23ec2 100644 --- a/packages/env/lib/build-docker-compose-config.js +++ b/packages/env/lib/build-docker-compose-config.js @@ -18,8 +18,8 @@ const { hasSameCoreSource } = require( './wordpress' ); /** * Gets the volume mounts for an individual service. * - * @param {WPServiceConfig} config The service config to get the mounts from. - * @param {string} wordpressDefault The default internal path for the WordPress + * @param {WPServiceConfig} config The service config to get the mounts from. + * @param {string} wordpressDefault The default internal path for the WordPress * source code (such as tests-wordpress). * * @return {string[]} An array of volumes to mount in string format. diff --git a/packages/env/lib/cache.js b/packages/env/lib/cache.js index af6fde6488421..d6b532c559f49 100644 --- a/packages/env/lib/cache.js +++ b/packages/env/lib/cache.js @@ -8,7 +8,7 @@ const fs = require( 'fs' ).promises; * Options for cache parsing. * * @typedef WPEnvCacheOptions - * @property {string} workDirectoryPath Path to the work directory located in ~/.wp-env. + * @property {string} workDirectoryPath Path to the work directory located in ~/.wp-env. */ const CACHE_FILE_NAME = 'wp-env-cache.json'; diff --git a/packages/env/lib/config/config.js b/packages/env/lib/config/config.js index 487d82f83d9bf..a3ed2fd17d91b 100644 --- a/packages/env/lib/config/config.js +++ b/packages/env/lib/config/config.js @@ -19,25 +19,25 @@ const md5 = require( '../md5' ); * wp-env configuration. * * @typedef WPConfig - * @property {string} name Name of the environment. - * @property {string} configDirectoryPath Path to the .wp-env.json file. - * @property {string} workDirectoryPath Path to the work directory located in ~/.wp-env. - * @property {string} dockerComposeConfigPath Path to the docker-compose.yml file. - * @property {boolean} detectedLocalConfig If true, wp-env detected local config and used it. - * @property {Object.} env Specific config for different environments. - * @property {boolean} debug True if debug mode is enabled. + * @property {string} name Name of the environment. + * @property {string} configDirectoryPath Path to the .wp-env.json file. + * @property {string} workDirectoryPath Path to the work directory located in ~/.wp-env. + * @property {string} dockerComposeConfigPath Path to the docker-compose.yml file. + * @property {boolean} detectedLocalConfig If true, wp-env detected local config and used it. + * @property {Object.} env Specific config for different environments. + * @property {boolean} debug True if debug mode is enabled. */ /** * Base-level config for any particular environment. (development/tests/etc) * * @typedef WPServiceConfig - * @property {?WPSource} coreSource The WordPress installation to load in the environment. - * @property {WPSource[]} pluginSources Plugins to load in the environment. - * @property {WPSource[]} themeSources Themes to load in the environment. - * @property {number} port The port to use. - * @property {Object} config Mapping of wp-config.php constants to their desired values. - * @property {Object.} mappings Mapping of WordPress directories to local directories which should be mounted. + * @property {?WPSource} coreSource The WordPress installation to load in the environment. + * @property {WPSource[]} pluginSources Plugins to load in the environment. + * @property {WPSource[]} themeSources Themes to load in the environment. + * @property {number} port The port to use. + * @property {Object} config Mapping of wp-config.php constants to their desired values. + * @property {Object.} mappings Mapping of WordPress directories to local directories which should be mounted. */ /** diff --git a/packages/env/lib/config/parse-config.js b/packages/env/lib/config/parse-config.js index 4d1e0333a532b..20f154d079eea 100644 --- a/packages/env/lib/config/parse-config.js +++ b/packages/env/lib/config/parse-config.js @@ -27,7 +27,7 @@ const HOME_PATH_PREFIX = `~${ path.sep }`; * internally. For example, `plugins: string[]` will be parsed into * `pluginSources: WPSource[]`. * - * @param {Object} config A config object to validate. + * @param {Object} config A config object to validate. * @param {Object} options * @param {string} options.workDirectoryPath Path to the work directory located in ~/.wp-env. * @return {WPServiceConfig} Parsed environment-level configuration. @@ -60,9 +60,9 @@ module.exports = function parseConfig( config, options ) { /** * Parses a source string into a source object. * - * @param {?string} sourceString The source string. See README.md for documentation on valid source string patterns. - * @param {Object} options - * @param {string} options.workDirectoryPath Path to the work directory located in ~/.wp-env. + * @param {?string} sourceString The source string. See README.md for documentation on valid source string patterns. + * @param {Object} options + * @param {string} options.workDirectoryPath Path to the work directory located in ~/.wp-env. * * @return {?WPSource} A source object. */ @@ -133,8 +133,8 @@ function parseSourceString( sourceString, { workDirectoryPath } ) { * property set correctly. Only the 'core' source requires a testsPath. * * @param {?WPSource} source A source object. - * @param {Object} options - * @param {string} options.workDirectoryPath Path to the work directory located in ~/.wp-env. + * @param {Object} options + * @param {string} options.workDirectoryPath Path to the work directory located in ~/.wp-env. * * @return {?WPSource} A source object. */ diff --git a/packages/env/lib/config/validate-config.js b/packages/env/lib/config/validate-config.js index 6a50904cb52f8..f99ea30074d2d 100644 --- a/packages/env/lib/config/validate-config.js +++ b/packages/env/lib/config/validate-config.js @@ -15,7 +15,7 @@ class ValidationError extends Error {} * Validates a config object by throwing a ValidationError if any of its properties * do not match the required format. * - * @param {Object} config A config object to validate. + * @param {Object} config A config object to validate. * @param {?string} envLocation Identifies if the error occured in a specific environment property. * @return {Object} The passed config object with no modifications. */ diff --git a/packages/env/lib/retry.js b/packages/env/lib/retry.js index b23705ee2cc06..014e5b7bffe81 100644 --- a/packages/env/lib/retry.js +++ b/packages/env/lib/retry.js @@ -11,10 +11,10 @@ const sleep = util.promisify( setTimeout ); /** * Performs the given action again and again until it does not throw an error. * - * @param {Function} action The action to perform. - * @param {Object} options - * @param {number} options.times How many times to try before giving up. - * @param {number} [options.delay=5000] How long, in milliseconds, to wait between each try. + * @param {Function} action The action to perform. + * @param {Object} options + * @param {number} options.times How many times to try before giving up. + * @param {number} [options.delay=5000] How long, in milliseconds, to wait between each try. */ module.exports = async function retry( action, { times, delay = 5000 } ) { let tries = 0; diff --git a/packages/env/lib/wordpress.js b/packages/env/lib/wordpress.js index 07705167ac1dc..d40740c178134 100644 --- a/packages/env/lib/wordpress.js +++ b/packages/env/lib/wordpress.js @@ -68,7 +68,7 @@ async function checkDatabaseConnection( { dockerComposeConfigPath, debug } ) { * * @param {WPEnvironment} environment The environment to configure. Either 'development' or 'tests'. * @param {WPConfig} config The wp-env config object. - * @param {Object} spinner A CLI spinner which indicates progress. + * @param {Object} spinner A CLI spinner which indicates progress. */ async function configureWordPress( environment, config, spinner ) { const installCommand = `wp core install --url="localhost:${ config.env[ environment ].port }" --title="${ config.name }" --admin_user=admin --admin_password=password --admin_email=wordpress@example.com --skip-email`; @@ -235,7 +235,7 @@ function areCoreSourcesDifferent( coreSource1, coreSource2 ) { * (.git, node_modules) and configuration files (wp-config.php). * * @param {string} fromPath Path to the WordPress directory to copy. - * @param {string} toPath Destination path. + * @param {string} toPath Destination path. */ async function copyCoreFiles( fromPath, toPath ) { await copyDir( fromPath, toPath, { diff --git a/packages/eslint-plugin/rules/i18n-text-domain.js b/packages/eslint-plugin/rules/i18n-text-domain.js index b47564738d06e..6f8a3761a9688 100644 --- a/packages/eslint-plugin/rules/i18n-text-domain.js +++ b/packages/eslint-plugin/rules/i18n-text-domain.js @@ -10,7 +10,7 @@ const { * Returns the text domain passed to the given translation function. * * @param {string} functionName Translation function name. - * @param {Array} args Function arguments. + * @param {Array} args Function arguments. * @return {undefined|*} Text domain argument. */ function getTextDomain( functionName, args ) { diff --git a/packages/eslint-plugin/utils/get-text-content-from-node.js b/packages/eslint-plugin/utils/get-text-content-from-node.js index 672f4f1aee7d4..2f74d4d9600a2 100644 --- a/packages/eslint-plugin/utils/get-text-content-from-node.js +++ b/packages/eslint-plugin/utils/get-text-content-from-node.js @@ -3,7 +3,7 @@ * * @see eslint-plugin-wpcalypso * - * @param {Object} node A Literal, TemplateLiteral or BinaryExpression (+) node + * @param {Object} node A Literal, TemplateLiteral or BinaryExpression (+) node * @return {string|boolean} The concatenated string or false. */ function getTextContentFromNode( node ) { diff --git a/packages/hooks/src/createAddHook.js b/packages/hooks/src/createAddHook.js index 3d545a2e824cf..b37346ff7ca5b 100644 --- a/packages/hooks/src/createAddHook.js +++ b/packages/hooks/src/createAddHook.js @@ -8,7 +8,7 @@ import { doAction } from './'; /** * Returns a function which, when invoked, will add a hook. * - * @param {Object} hooks Stored hooks, keyed by hook name. + * @param {Object} hooks Stored hooks, keyed by hook name. * * @return {Function} Function that adds a new hook. */ diff --git a/packages/hooks/src/createCurrentHook.js b/packages/hooks/src/createCurrentHook.js index c36cab8b43df2..c7a14cb0a9da9 100644 --- a/packages/hooks/src/createCurrentHook.js +++ b/packages/hooks/src/createCurrentHook.js @@ -3,7 +3,7 @@ * currently running hook, or `null` if no hook of the given type is currently * running. * - * @param {Object} hooks Stored hooks, keyed by hook name. + * @param {Object} hooks Stored hooks, keyed by hook name. * * @return {Function} Function that returns the current hook. */ diff --git a/packages/hooks/src/createDidHook.js b/packages/hooks/src/createDidHook.js index 9075507b3d865..bb111a045b10a 100644 --- a/packages/hooks/src/createDidHook.js +++ b/packages/hooks/src/createDidHook.js @@ -7,7 +7,7 @@ import validateHookName from './validateHookName.js'; * Returns a function which, when invoked, will return the number of times a * hook has been called. * - * @param {Object} hooks Stored hooks, keyed by hook name. + * @param {Object} hooks Stored hooks, keyed by hook name. * * @return {Function} Function that returns a hook's call count. */ @@ -15,7 +15,7 @@ function createDidHook( hooks ) { /** * Returns the number of times an action has been fired. * - * @param {string} hookName The hook name to check. + * @param {string} hookName The hook name to check. * * @return {number} The number of times the hook has run. */ diff --git a/packages/hooks/src/createDoingHook.js b/packages/hooks/src/createDoingHook.js index 055e99e52cedd..6bbfaf1b5c905 100644 --- a/packages/hooks/src/createDoingHook.js +++ b/packages/hooks/src/createDoingHook.js @@ -2,7 +2,7 @@ * Returns a function which, when invoked, will return whether a hook is * currently being executed. * - * @param {Object} hooks Stored hooks, keyed by hook name. + * @param {Object} hooks Stored hooks, keyed by hook name. * * @return {Function} Function that returns whether a hook is currently * being executed. @@ -11,7 +11,7 @@ function createDoingHook( hooks ) { /** * Returns whether a hook is currently being executed. * - * @param {?string} hookName The name of the hook to check for. If + * @param {?string} hookName The name of the hook to check for. If * omitted, will check for any hook being executed. * * @return {boolean} Whether the hook is being executed. diff --git a/packages/hooks/src/createHasHook.js b/packages/hooks/src/createHasHook.js index d92f884560b5e..77e30792d555b 100644 --- a/packages/hooks/src/createHasHook.js +++ b/packages/hooks/src/createHasHook.js @@ -2,7 +2,7 @@ * Returns a function which, when invoked, will return whether any handlers are * attached to a particular hook. * - * @param {Object} hooks Stored hooks, keyed by hook name. + * @param {Object} hooks Stored hooks, keyed by hook name. * * @return {Function} Function that returns whether any handlers are * attached to a particular hook and optional namespace. diff --git a/packages/hooks/src/createRemoveHook.js b/packages/hooks/src/createRemoveHook.js index f2cf9456d45f8..edfb62fed6d8e 100644 --- a/packages/hooks/src/createRemoveHook.js +++ b/packages/hooks/src/createRemoveHook.js @@ -9,8 +9,8 @@ import { doAction } from './'; * Returns a function which, when invoked, will remove a specified hook or all * hooks by the given name. * - * @param {Object} hooks Stored hooks, keyed by hook name. - * @param {boolean} removeAll Whether to remove all callbacks for a hookName, without regard to namespace. Used to create `removeAll*` functions. + * @param {Object} hooks Stored hooks, keyed by hook name. + * @param {boolean} removeAll Whether to remove all callbacks for a hookName, without regard to namespace. Used to create `removeAll*` functions. * * @return {Function} Function that removes hooks. */ @@ -19,8 +19,8 @@ function createRemoveHook( hooks, removeAll ) { * Removes the specified callback (or all callbacks) from the hook with a * given hookName and namespace. * - * @param {string} hookName The name of the hook to modify. - * @param {string} namespace The unique namespace identifying the callback in the form `vendor/plugin/function`. + * @param {string} hookName The name of the hook to modify. + * @param {string} namespace The unique namespace identifying the callback in the form `vendor/plugin/function`. * * @return {number} The number of callbacks removed. */ diff --git a/packages/hooks/src/createRunHook.js b/packages/hooks/src/createRunHook.js index 311b1cc905262..ecd05c891dc0a 100644 --- a/packages/hooks/src/createRunHook.js +++ b/packages/hooks/src/createRunHook.js @@ -3,8 +3,8 @@ * registered to a hook of the specified type, optionally returning the final * value of the call chain. * - * @param {Object} hooks Stored hooks, keyed by hook name. - * @param {?boolean} returnFirstArg Whether each hook callback is expected to + * @param {Object} hooks Stored hooks, keyed by hook name. + * @param {?boolean} returnFirstArg Whether each hook callback is expected to * return its first argument. * * @return {Function} Function that runs hook callbacks. @@ -13,8 +13,8 @@ function createRunHook( hooks, returnFirstArg ) { /** * Runs all callbacks for the specified hook. * - * @param {string} hookName The name of the hook to run. - * @param {...*} args Arguments to pass to the hook callbacks. + * @param {string} hookName The name of the hook to run. + * @param {...*} args Arguments to pass to the hook callbacks. * * @return {*} Return value of runner, if applicable. */ diff --git a/packages/hooks/src/validateHookName.js b/packages/hooks/src/validateHookName.js index de93ecdd306df..b7c3723c21edc 100644 --- a/packages/hooks/src/validateHookName.js +++ b/packages/hooks/src/validateHookName.js @@ -1,7 +1,7 @@ /** * Validate a hookName string. * - * @param {string} hookName The hook name to validate. Should be a non empty string containing + * @param {string} hookName The hook name to validate. Should be a non empty string containing * only numbers, letters, dashes, periods and underscores. Also, * the hook name cannot begin with `__`. * diff --git a/packages/hooks/src/validateNamespace.js b/packages/hooks/src/validateNamespace.js index bd004482415f8..1fab6bef19df7 100644 --- a/packages/hooks/src/validateNamespace.js +++ b/packages/hooks/src/validateNamespace.js @@ -1,7 +1,7 @@ /** * Validate a namespace string. * - * @param {string} namespace The namespace to validate - should take the form + * @param {string} namespace The namespace to validate - should take the form * `vendor/plugin/function`. * * @return {boolean} Whether the namespace is valid. diff --git a/packages/i18n/src/create-i18n.js b/packages/i18n/src/create-i18n.js index 0b0b4cd1826d1..d1865992d2617 100644 --- a/packages/i18n/src/create-i18n.js +++ b/packages/i18n/src/create-i18n.js @@ -15,7 +15,11 @@ import Tannin from 'tannin'; */ const DEFAULT_LOCALE_DATA = { '': { - /** @param {number} n */ + /** + * Plural forms. + * + * @param {number} n + **/ plural_forms( n ) { return n === 1 ? 0 : 1; }, @@ -40,8 +44,8 @@ const DEFAULT_LOCALE_DATA = { /** * Create an i18n instance * - * @param {LocaleData} [initialData] Locale data configuration. - * @param {string} [initialDomain] Domain for which configuration applies. + * @param {LocaleData} [initialData] Locale data configuration. + * @param {string} [initialDomain] Domain for which configuration applies. * @return {I18n} I18n instance */ export const createI18n = ( initialData, initialDomain ) => { diff --git a/packages/i18n/src/sprintf.js b/packages/i18n/src/sprintf.js index 90eca75beae88..f3004c5d092bc 100644 --- a/packages/i18n/src/sprintf.js +++ b/packages/i18n/src/sprintf.js @@ -17,8 +17,8 @@ const logErrorOnce = memoize( console.error ); // eslint-disable-line no-console * Returns a formatted string. If an error occurs in applying the format, the * original format string is returned. * - * @param {string} format The format of the string to generate. - * @param {...*} args Arguments to apply to the format. + * @param {string} format The format of the string to generate. + * @param {...*} args Arguments to apply to the format. * * @see http://www.diveintojavascript.com/projects/javascript-sprintf * diff --git a/packages/i18n/tools/pot-to-php.js b/packages/i18n/tools/pot-to-php.js index 7917f5b62a4bc..78d52d0b54cec 100755 --- a/packages/i18n/tools/pot-to-php.js +++ b/packages/i18n/tools/pot-to-php.js @@ -36,8 +36,8 @@ function escapeSingleQuotes( input ) { * Converts a translation parsed from the POT file to lines of WP PHP. * * @param {Object} translation The translation to convert. - * @param {string} textdomain The text domain to use in the WordPress translation function call. - * @param {string} context The context for the translation. + * @param {string} textdomain The text domain to use in the WordPress translation function call. + * @param {string} context The context for the translation. * @return {string} Lines of PHP that match the translation. */ function convertTranslationToPHP( translation, textdomain, context = '' ) { diff --git a/packages/interface/src/store/selectors.js b/packages/interface/src/store/selectors.js index 8dabd79a8e304..eb7be3697349b 100644 --- a/packages/interface/src/store/selectors.js +++ b/packages/interface/src/store/selectors.js @@ -19,8 +19,8 @@ function getSingleEnableItem( state, itemType, scope ) { /** * Returns the complementary area that is active in a given scope. * - * @param {Object} state Global application state. - * @param {string} scope Item scope. + * @param {Object} state Global application state. + * @param {string} scope Item scope. * * @return {string} The complementary area that is active in the given scope. */ @@ -49,9 +49,9 @@ function isMultipleEnabledItemEnabled( state, itemType, scope, item ) { /** * Returns a boolean indicating if an item is pinned or not. * - * @param {Object} state Global application state. - * @param {string} scope Scope. - * @param {string} item Item to check. + * @param {Object} state Global application state. + * @param {string} scope Scope. + * @param {string} item Item to check. * * @return {boolean} True if the item is pinned and false otherwise. */ diff --git a/packages/jest-console/src/index.js b/packages/jest-console/src/index.js index 0c10020455dcf..0664e1c9ae1b1 100644 --- a/packages/jest-console/src/index.js +++ b/packages/jest-console/src/index.js @@ -13,7 +13,7 @@ import supportedMatchers from './supported-matchers'; * Sets spy on the console object's method to make it possible to fail test when method called without assertion. * * @param {string} matcherName Name of Jest matcher. - * @param {string} methodName Name of console method. + * @param {string} methodName Name of console method. */ const setConsoleMethodSpy = ( matcherName, methodName ) => { const spy = jest diff --git a/packages/keyboard-shortcuts/src/hooks/use-shortcut.js b/packages/keyboard-shortcuts/src/hooks/use-shortcut.js index f6b0f4e584b90..d8cc928c8772d 100644 --- a/packages/keyboard-shortcuts/src/hooks/use-shortcut.js +++ b/packages/keyboard-shortcuts/src/hooks/use-shortcut.js @@ -7,9 +7,9 @@ import { useKeyboardShortcut } from '@wordpress/compose'; /** * Attach a keyboard shortcut handler. * - * @param {string} name Shortcut name. + * @param {string} name Shortcut name. * @param {Function} callback Shortcut callback. - * @param {Object} options Shortcut options. + * @param {Object} options Shortcut options. */ function useShortcut( name, callback, options ) { const shortcuts = useSelect( diff --git a/packages/keyboard-shortcuts/src/store/selectors.js b/packages/keyboard-shortcuts/src/store/selectors.js index 4bf4c4c9b9c5a..43b75ddf4233b 100644 --- a/packages/keyboard-shortcuts/src/store/selectors.js +++ b/packages/keyboard-shortcuts/src/store/selectors.js @@ -41,8 +41,8 @@ const FORMATTING_METHODS = { /** * Returns a string representing the key combination. * - * @param {?WPShortcutKeyCombination} shortcut Key combination. - * @param {keyof FORMATTING_METHODS} representation Type of representation + * @param {?WPShortcutKeyCombination} shortcut Key combination. + * @param {keyof FORMATTING_METHODS} representation Type of representation * (display, raw, ariaLabel). * * @return {string?} Shortcut representation. @@ -74,9 +74,9 @@ export function getShortcutKeyCombination( state, name ) { /** * Returns a string representing the main key combination for a given shortcut name. * - * @param {Object} state Global state. - * @param {string} name Shortcut name. - * @param {keyof FORMATTING_METHODS} representation Type of representation + * @param {Object} state Global state. + * @param {string} name Shortcut name. + * @param {keyof FORMATTING_METHODS} representation Type of representation * (display, raw, ariaLabel). * * @return {string?} Shortcut representation. diff --git a/packages/keycodes/src/platform.js b/packages/keycodes/src/platform.js index 19295d47b1f4f..21fb95b29c4bb 100644 --- a/packages/keycodes/src/platform.js +++ b/packages/keycodes/src/platform.js @@ -6,7 +6,7 @@ import { includes } from 'lodash'; /** * Return true if platform is MacOS. * - * @param {Object} _window window object by default; used for DI testing. + * @param {Object} _window window object by default; used for DI testing. * * @return {boolean} True if MacOS; false otherwise. */ diff --git a/packages/list-reusable-blocks/src/utils/file.js b/packages/list-reusable-blocks/src/utils/file.js index 5db29e9bebac8..f4cff155c591f 100644 --- a/packages/list-reusable-blocks/src/utils/file.js +++ b/packages/list-reusable-blocks/src/utils/file.js @@ -27,7 +27,7 @@ export function download( fileName, content, contentType ) { /** * Reads the textual content of the given file. * - * @param {File} file File. + * @param {File} file File. * @return {Promise} Content of the file. */ export function readTextFile( file ) { diff --git a/packages/list-reusable-blocks/src/utils/import.js b/packages/list-reusable-blocks/src/utils/import.js index e885cbb6b2b24..d35dc97ee81d2 100644 --- a/packages/list-reusable-blocks/src/utils/import.js +++ b/packages/list-reusable-blocks/src/utils/import.js @@ -16,7 +16,7 @@ import { readTextFile } from './file'; /** * Import a reusable block from a JSON file. * - * @param {File} file File. + * @param {File} file File. * @return {Promise} Promise returning the imported reusable block. */ async function importReusableBlock( file ) { diff --git a/packages/media-utils/src/utils/upload-media.js b/packages/media-utils/src/utils/upload-media.js index aba998e4e2dd4..f328c239e94ad 100644 --- a/packages/media-utils/src/utils/upload-media.js +++ b/packages/media-utils/src/utils/upload-media.js @@ -55,14 +55,14 @@ export function getMimeTypesArray( wpMimeTypesObject ) { * * TODO: future enhancement to add an upload indicator. * - * @param {Object} $0 Parameters object passed to the function. - * @param {?Array} $0.allowedTypes Array with the types of media that can be uploaded, if unset all types are allowed. - * @param {?Object} $0.additionalData Additional data to include in the request. - * @param {Array} $0.filesList List of files. - * @param {?number} $0.maxUploadFileSize Maximum upload size in bytes allowed for the site. - * @param {Function} $0.onError Function called when an error happens. - * @param {Function} $0.onFileChange Function called each time a file or a temporary representation of the file is available. - * @param {?Object} $0.wpAllowedMimeTypes List of allowed mime types and file extensions. + * @param {Object} $0 Parameters object passed to the function. + * @param {?Array} $0.allowedTypes Array with the types of media that can be uploaded, if unset all types are allowed. + * @param {?Object} $0.additionalData Additional data to include in the request. + * @param {Array} $0.filesList List of files. + * @param {?number} $0.maxUploadFileSize Maximum upload size in bytes allowed for the site. + * @param {Function} $0.onError Function called when an error happens. + * @param {Function} $0.onFileChange Function called each time a file or a temporary representation of the file is available. + * @param {?Object} $0.wpAllowedMimeTypes List of allowed mime types and file extensions. */ export async function uploadMedia( { allowedTypes, diff --git a/packages/notices/src/store/actions.js b/packages/notices/src/store/actions.js index 9f9acc3665e27..97d2ef9918c37 100644 --- a/packages/notices/src/store/actions.js +++ b/packages/notices/src/store/actions.js @@ -11,10 +11,10 @@ import { DEFAULT_CONTEXT, DEFAULT_STATUS } from './constants'; /** * @typedef {Object} WPNoticeAction Object describing a user action option associated with a notice. * - * @property {string} label Message to use as action label. - * @property {?string} url Optional URL of resource if action incurs + * @property {string} label Message to use as action label. + * @property {?string} url Optional URL of resource if action incurs * browser navigation. - * @property {?Function} onClick Optional function to invoke when action is + * @property {?Function} onClick Optional function to invoke when action is * triggered by user. * */ diff --git a/packages/notices/src/store/selectors.js b/packages/notices/src/store/selectors.js index 0517d93171432..9e70569f0fb20 100644 --- a/packages/notices/src/store/selectors.js +++ b/packages/notices/src/store/selectors.js @@ -19,26 +19,26 @@ const DEFAULT_NOTICES = []; /** * @typedef {Object} WPNotice Notice object. * - * @property {string} id Unique identifier of notice. - * @property {string} status Status of notice, one of `success`, + * @property {string} id Unique identifier of notice. + * @property {string} status Status of notice, one of `success`, * `info`, `error`, or `warning`. Defaults * to `info`. - * @property {string} content Notice message. - * @property {string} spokenMessage Audibly announced message text used by + * @property {string} content Notice message. + * @property {string} spokenMessage Audibly announced message text used by * assistive technologies. - * @property {string} __unstableHTML Notice message as raw HTML. Intended to + * @property {string} __unstableHTML Notice message as raw HTML. Intended to * serve primarily for compatibility of * server-rendered notices, and SHOULD NOT * be used for notices. It is subject to * removal without notice. - * @property {boolean} isDismissible Whether the notice can be dismissed by + * @property {boolean} isDismissible Whether the notice can be dismissed by * user. Defaults to `true`. - * @property {string} type Type of notice, one of `default`, + * @property {string} type Type of notice, one of `default`, * or `snackbar`. Defaults to `default`. - * @property {boolean} speak Whether the notice content should be + * @property {boolean} speak Whether the notice content should be * announced to screen readers. Defaults to * `true`. - * @property {WPNoticeAction[]} actions User actions to present with notice. + * @property {WPNoticeAction[]} actions User actions to present with notice. * */ diff --git a/packages/nux/src/store/reducer.js b/packages/nux/src/store/reducer.js index 07635d66189db..373e4781f5235 100644 --- a/packages/nux/src/store/reducer.js +++ b/packages/nux/src/store/reducer.js @@ -7,7 +7,7 @@ import { combineReducers } from '@wordpress/data'; * Reducer that tracks which tips are in a guide. Each guide is represented by * an array which contains the tip identifiers contained within that guide. * - * @param {Array} state Current state. + * @param {Array} state Current state. * @param {Object} action Dispatched action. * * @return {Array} Updated state. @@ -24,8 +24,8 @@ export function guides( state = [], action ) { /** * Reducer that tracks whether or not tips are globally enabled. * - * @param {boolean} state Current state. - * @param {Object} action Dispatched action. + * @param {boolean} state Current state. + * @param {Object} action Dispatched action. * * @return {boolean} Updated state. */ diff --git a/packages/react-native-bridge/index.js b/packages/react-native-bridge/index.js index a3bc1690ac7dd..136a5472eae9b 100644 --- a/packages/react-native-bridge/index.js +++ b/packages/react-native-bridge/index.js @@ -94,7 +94,7 @@ export function subscribeUpdateCapabilities( callback ) { /** * @callback FnReplaceBlockCompletion - * @param {string} html the HTML to replace the block. + * @param {string} html the HTML to replace the block. * @param {string} clientId the clientId of the block to be replaced. */ @@ -112,10 +112,10 @@ export function subscribeReplaceBlock( callback ) { * * Kinds of media source can be device library, camera, etc. * - * @param {string} source The media source to request media from. - * @param {Array} filter Array of media types to filter the media to select. - * @param {boolean} multiple Is multiple selection allowed? - * @param {Function} callback RN Callback function to be called with the selected media objects. + * @param {string} source The media source to request media from. + * @param {Array} filter Array of media types to filter the media to select. + * @param {boolean} multiple Is multiple selection allowed? + * @param {Function} callback RN Callback function to be called with the selected media objects. */ export function requestMediaPicker( source, filter, multiple, callback ) { RNReactNativeGutenbergBridge.requestMediaPickFrom( @@ -131,10 +131,10 @@ export function requestMediaPicker( source, filter, multiple, callback ) { * * A way to show unsupported blocks to the user is to render it on a web view. * - * @param {string} htmlContent Raw html content of the block. + * @param {string} htmlContent Raw html content of the block. * @param {string} blockClientId the clientId of the block. - * @param {string} blockName the internal system block name. - * @param {string} blockTitle the user-facing, localized block name. + * @param {string} blockName the internal system block name. + * @param {string} blockTitle the user-facing, localized block name. */ export function requestUnsupportedBlockFallback( htmlContent, diff --git a/packages/redux-routine/src/runtime.js b/packages/redux-routine/src/runtime.js index d534baae4efc0..1148ea1af5ccd 100644 --- a/packages/redux-routine/src/runtime.js +++ b/packages/redux-routine/src/runtime.js @@ -13,8 +13,8 @@ import { isActionOfType, isAction } from './is-action'; /** * Create a co-routine runtime. * - * @param {Object} controls Object of control handlers. - * @param {Function} dispatch Unhandled action dispatch. + * @param {Object} controls Object of control handlers. + * @param {Function} dispatch Unhandled action dispatch. * * @return {Function} co-routine runtime */ diff --git a/packages/rich-text/README.md b/packages/rich-text/README.md index 30ed4296d162f..50f02bf170444 100644 --- a/packages/rich-text/README.md +++ b/packages/rich-text/README.md @@ -84,6 +84,7 @@ _Parameters_ - _$1.range_ `[Range]`: Range to create value from. - _$1.multilineTag_ `[string]`: Multiline tag if the structure is multiline. - _$1.multilineWrapperTags_ `[Array]`: Tags where lines can be found if nesting is possible. +- _$1.\_\_unstableIsEditableTree_ `[boolean]`: - _$1.preserveWhiteSpace_ `[?boolean]`: Whether or not to collapse white space characters. _Returns_ @@ -113,6 +114,10 @@ Gets the active object, if there is any. _Parameters_ - _value_ `Object`: Value to inspect. +- _value.start_ `number`: +- _value.end_ `number`: +- _value.replacements_ `Array`: +- _value.text_ `string`: _Returns_ @@ -126,6 +131,7 @@ Get the textual content of a Rich Text value. This is similar to _Parameters_ - _value_ `Object`: Value to use. +- _value.text_ `string`: _Returns_ @@ -176,6 +182,8 @@ is no selection, `undefined` will be returned. This is similar to _Parameters_ - _value_ `Object`: The rich text value to check. +- _value.start_ `[number]`: +- _value.end_ `[number]`: _Returns_ @@ -189,6 +197,7 @@ objects (such as images). _Parameters_ - _value_ `Object`: Value to use. +- _value.text_ `string`: _Returns_ @@ -263,6 +272,11 @@ is similar to `String.prototype.replace`. _Parameters_ - _value_ `Object`: The value to modify. +- _value.formats_ `Array`: +- _value.replacements_ `Array`: +- _value.text_ `string`: +- _value.start_ `number`: +- _value.end_ `number`: - _pattern_ `(RegExp|string)`: A RegExp object or literal. Can also be a string. It is treated as a verbatim string and is not interpreted as a regular expression. Only the first occurrence will be replaced. - _replacement_ `(Function|string)`: The match or matches are replaced with the specified or the value returned by the specified function. diff --git a/packages/rich-text/src/component/use-boundary-style.js b/packages/rich-text/src/component/use-boundary-style.js index 2636007521b1e..6b1f70cecfe64 100644 --- a/packages/rich-text/src/component/use-boundary-style.js +++ b/packages/rich-text/src/component/use-boundary-style.js @@ -6,6 +6,10 @@ import { useEffect } from '@wordpress/element'; /** * Calculates and renders the format boundary style when the active formats * change. + * + * @param {Object} $1 Named arguments. + * @param {Array} [$1.activeFormats] + * @param {Object} $1.ref */ export function useBoundaryStyle( { activeFormats, ref } ) { useEffect( () => { diff --git a/packages/rich-text/src/concat.js b/packages/rich-text/src/concat.js index 07be12140db91..9997607e216ff 100644 --- a/packages/rich-text/src/concat.js +++ b/packages/rich-text/src/concat.js @@ -9,8 +9,8 @@ import { create } from './create'; * Concats a pair of rich text values. Not that this mutates `a` and does NOT * normalise formats! * - * @param {Object} a Value to mutate. - * @param {Object} b Value to add read from. + * @param {Object} a Value to mutate. + * @param {Object} b Value to add read from. * * @return {Object} `a`, mutated. */ diff --git a/packages/rich-text/src/create.js b/packages/rich-text/src/create.js index 89c8d298da686..bd32b3c2e8876 100644 --- a/packages/rich-text/src/create.js +++ b/packages/rich-text/src/create.js @@ -121,17 +121,18 @@ function toFormat( { type, attributes } ) { * `start` and `end` state which text indices are selected. They are only * provided if a `Range` was given. * - * @param {Object} [$1] Optional named arguments. - * @param {Element} [$1.element] Element to create value from. - * @param {string} [$1.text] Text to create value from. - * @param {string} [$1.html] HTML to create value from. - * @param {Range} [$1.range] Range to create value from. - * @param {string} [$1.multilineTag] Multiline tag if the structure is - * multiline. - * @param {Array} [$1.multilineWrapperTags] Tags where lines can be found if - * nesting is possible. - * @param {?boolean} [$1.preserveWhiteSpace] Whether or not to collapse white - * space characters. + * @param {Object} [$1] Optional named arguments. + * @param {Element} [$1.element] Element to create value from. + * @param {string} [$1.text] Text to create value from. + * @param {string} [$1.html] HTML to create value from. + * @param {Range} [$1.range] Range to create value from. + * @param {string} [$1.multilineTag] Multiline tag if the structure is + * multiline. + * @param {Array} [$1.multilineWrapperTags] Tags where lines can be found if + * nesting is possible. + * @param {boolean} [$1.__unstableIsEditableTree] + * @param {?boolean} [$1.preserveWhiteSpace] Whether or not to collapse white + * space characters. * * @return {Object} A rich text value. */ @@ -299,15 +300,17 @@ function removePadding( string ) { /** * Creates a Rich Text value from a DOM element and range. * - * @param {Object} $1 Named argements. - * @param {?Element} $1.element Element to create value from. - * @param {?Range} $1.range Range to create value from. - * @param {?string} $1.multilineTag Multiline tag if the structure is - * multiline. - * @param {?Array} $1.multilineWrapperTags Tags where lines can be found if - * nesting is possible. - * @param {?boolean} $1.preserveWhiteSpace Whether or not to collapse white - * space characters. + * @param {Object} $1 Named argements. + * @param {?Element} $1.element Element to create value from. + * @param {?Range} $1.range Range to create value from. + * @param {?string} $1.multilineTag Multiline tag if the structure is + * multiline. + * @param {?Array} $1.multilineWrapperTags Tags where lines can be found if + * nesting is possible. + * @param {?Array} $1.currentWrapperTags + * @param {?boolean} $1.isEditableTree + * @param {?boolean} $1.preserveWhiteSpace Whether or not to collapse white + * space characters. * * @return {Object} A rich text value. */ @@ -475,6 +478,7 @@ function createFromElement( { * nesting is possible. * @param {boolean} $1.currentWrapperTags Whether to prepend a line * separator. + * @param {?boolean} $1.isEditableTree * @param {?boolean} $1.preserveWhiteSpace Whether or not to collapse white * space characters. * @@ -537,8 +541,8 @@ function createFromMultilineElement( { /** * Gets the attributes of an element in object shape. * - * @param {Object} $1 Named argements. - * @param {Element} $1.element Element to get attributes from. + * @param {Object} $1 Named argements. + * @param {Element} $1.element Element to get attributes from. * * @return {?Object} Attribute object or `undefined` if the element has no * attributes. diff --git a/packages/rich-text/src/get-active-formats.js b/packages/rich-text/src/get-active-formats.js index 8e8a27df5d803..de94544c7b073 100644 --- a/packages/rich-text/src/get-active-formats.js +++ b/packages/rich-text/src/get-active-formats.js @@ -1,12 +1,12 @@ /** * Gets the all format objects at the start of the selection. * - * @param {Object} value Value to inspect. - * @param {Array} value.formats Formats object data values. - * @param {number} value.start Index to start from. - * @param {number} value.end Index to end. - * @param {Array} value.activeFormats Array to return if there are active formats. - * @param {Array} EMPTY_ACTIVE_FORMATS Array to return if there are no active + * @param {Object} value Value to inspect. + * @param {Array} value.formats Formats object data values. + * @param {number} value.start Index to start from. + * @param {number} value.end Index to end. + * @param {Array} value.activeFormats Array to return if there are active formats. + * @param {Array} EMPTY_ACTIVE_FORMATS Array to return if there are no active * formats. * * @return {?Object} Active format objects. diff --git a/packages/rich-text/src/get-active-object.js b/packages/rich-text/src/get-active-object.js index e324521284597..1320471e591bc 100644 --- a/packages/rich-text/src/get-active-object.js +++ b/packages/rich-text/src/get-active-object.js @@ -7,7 +7,11 @@ import { OBJECT_REPLACEMENT_CHARACTER } from './special-characters'; /** * Gets the active object, if there is any. * - * @param {Object} value Value to inspect. + * @param {Object} value Value to inspect. + * @param {number} value.start + * @param {number} value.end + * @param {Array} value.replacements + * @param {string} value.text * * @return {?Object} Active object, or undefined. */ diff --git a/packages/rich-text/src/get-last-child-index.js b/packages/rich-text/src/get-last-child-index.js index 0fc4aeb32ff3e..0dfdce33bf452 100644 --- a/packages/rich-text/src/get-last-child-index.js +++ b/packages/rich-text/src/get-last-child-index.js @@ -7,8 +7,10 @@ import { LINE_SEPARATOR } from './special-characters'; /** * Gets the line index of the last child in the list. * - * @param {Object} value Value to search. - * @param {number} lineIndex Line index of a list item in the list. + * @param {Object} value Value to search. + * @param {string} value.text + * @param {Array} value.replacements + * @param {number} lineIndex Line index of a list item in the list. * * @return {Array} The index of the last child. */ diff --git a/packages/rich-text/src/get-line-index.js b/packages/rich-text/src/get-line-index.js index ff44efb98fceb..9a76ea320626e 100644 --- a/packages/rich-text/src/get-line-index.js +++ b/packages/rich-text/src/get-line-index.js @@ -8,10 +8,12 @@ import { LINE_SEPARATOR } from './special-characters'; * Gets the currently selected line index, or the first line index if the * selection spans over multiple items. * - * @param {Object} value Value to get the line index from. - * @param {boolean} startIndex Optional index that should be contained by the - * line. Defaults to the selection start of the - * value. + * @param {Object} value Value to get the line index from. + * @param {number} value.start Value to get the line index from. + * @param {string} value.text Value to get the line index from. + * @param {boolean} startIndex Optional index that should be contained by the + * line. Defaults to the selection start of the + * value. * * @return {?boolean} The line index. Undefined if not found. */ diff --git a/packages/rich-text/src/get-parent-line-index.js b/packages/rich-text/src/get-parent-line-index.js index 1b0a0ecb5cf48..14924dc8407d9 100644 --- a/packages/rich-text/src/get-parent-line-index.js +++ b/packages/rich-text/src/get-parent-line-index.js @@ -9,8 +9,10 @@ import { LINE_SEPARATOR } from './special-characters'; * go through every list item until we find one with exactly one format type * less. * - * @param {Object} value Value to search. - * @param {number} lineIndex Line index of a child list item. + * @param {Object} value Value to search. + * @param {string} value.text + * @param {Array} value.replacements + * @param {number} lineIndex Line index of a child list item. * * @return {Array} The parent list line index. */ diff --git a/packages/rich-text/src/get-text-content.js b/packages/rich-text/src/get-text-content.js index 75961a2b242ba..dac3a1b0accfc 100644 --- a/packages/rich-text/src/get-text-content.js +++ b/packages/rich-text/src/get-text-content.js @@ -2,7 +2,8 @@ * Get the textual content of a Rich Text value. This is similar to * `Element.textContent`. * - * @param {Object} value Value to use. + * @param {Object} value Value to use. + * @param {string} value.text * * @return {string} The text content. */ diff --git a/packages/rich-text/src/indent-list-items.js b/packages/rich-text/src/indent-list-items.js index b444cfbf448bc..b27f50ed17bc7 100644 --- a/packages/rich-text/src/indent-list-items.js +++ b/packages/rich-text/src/indent-list-items.js @@ -9,8 +9,10 @@ import { canIndentListItems } from './can-indent-list-items'; /** * Gets the line index of the first previous list item with higher indentation. * - * @param {Object} value Value to search. - * @param {number} lineIndex Line index of the list item to compare with. + * @param {Object} value Value to search. + * @param {string} value.text + * @param {Array} value.replacements + * @param {number} lineIndex Line index of the list item to compare with. * * @return {boolean} The line index. */ diff --git a/packages/rich-text/src/is-active-list-type.js b/packages/rich-text/src/is-active-list-type.js index 3f4c7d772d3d8..684c2c28fbc6e 100644 --- a/packages/rich-text/src/is-active-list-type.js +++ b/packages/rich-text/src/is-active-list-type.js @@ -7,9 +7,9 @@ import { getLineIndex } from './get-line-index'; /** * Wether or not the selected list has the given tag name. * - * @param {Object} value The value to check. - * @param {string} type The tag name the list should have. - * @param {string} rootType The current root tag name, to compare with in case + * @param {Object} value The value to check. + * @param {string} type The tag name the list should have. + * @param {string} rootType The current root tag name, to compare with in case * nothing is selected. * * @return {boolean} True if the current list type matches `type`, false if not. diff --git a/packages/rich-text/src/is-collapsed.js b/packages/rich-text/src/is-collapsed.js index 7014d510377c2..4d9c75b4452d8 100644 --- a/packages/rich-text/src/is-collapsed.js +++ b/packages/rich-text/src/is-collapsed.js @@ -4,7 +4,9 @@ * is no selection, `undefined` will be returned. This is similar to * `window.getSelection().isCollapsed()`. * - * @param {Object} value The rich text value to check. + * @param {Object} value The rich text value to check. + * @param {number} [value.start] + * @param {number} [value.end] * * @return {boolean|undefined} True if the selection is collapsed, false if not, * undefined if there is no selection. diff --git a/packages/rich-text/src/is-empty.js b/packages/rich-text/src/is-empty.js index 14fbbdbe763c2..5d70635bd351e 100644 --- a/packages/rich-text/src/is-empty.js +++ b/packages/rich-text/src/is-empty.js @@ -7,7 +7,8 @@ import { LINE_SEPARATOR } from './special-characters'; * Check if a Rich Text value is Empty, meaning it contains no text or any * objects (such as images). * - * @param {Object} value Value to use. + * @param {Object} value Value to use. + * @param {string} value.text * * @return {boolean} True if the value is empty, false if not. */ @@ -19,7 +20,10 @@ export function isEmpty( { text } ) { * Check if the current collapsed selection is on an empty line in case of a * multiline value. * - * @param {Object} value Value te check. + * @param {Object} value Value te check. + * @param {string} value.text + * @param {number} value.start + * @param {number} value.end * * @return {boolean} True if the line is empty, false if not. */ diff --git a/packages/rich-text/src/register-format-type.js b/packages/rich-text/src/register-format-type.js index 7bf90967169d5..339c22268a157 100644 --- a/packages/rich-text/src/register-format-type.js +++ b/packages/rich-text/src/register-format-type.js @@ -20,8 +20,8 @@ import { select, dispatch } from '@wordpress/data'; * Registers a new format provided a unique name and an object defining its * behavior. * - * @param {string} name Format name. - * @param {WPFormat} settings Format settings. + * @param {string} name Format name. + * @param {WPFormat} settings Format settings. * * @return {WPFormat|undefined} The format, if it has been successfully registered; * otherwise `undefined`. diff --git a/packages/rich-text/src/remove-line-separator.js b/packages/rich-text/src/remove-line-separator.js index a30b150b99027..3f4073535175c 100644 --- a/packages/rich-text/src/remove-line-separator.js +++ b/packages/rich-text/src/remove-line-separator.js @@ -10,7 +10,7 @@ import { remove } from './remove'; * Removes a line separator character, if existing, from a Rich Text value at the current * indices. If no line separator exists on the indices it will return undefined. * - * @param {Object} value Value to modify. + * @param {Object} value Value to modify. * @param {boolean} backward indicates if are removing from the start index or the end index. * * @return {Object|undefined} A new value with the line separator removed. Or undefined if no line separator is found on the position. diff --git a/packages/rich-text/src/replace.js b/packages/rich-text/src/replace.js index 597fcfec59f09..9ba7bf1dc3ef1 100644 --- a/packages/rich-text/src/replace.js +++ b/packages/rich-text/src/replace.js @@ -8,15 +8,20 @@ import { normaliseFormats } from './normalise-formats'; * Search a Rich Text value and replace the match(es) with `replacement`. This * is similar to `String.prototype.replace`. * - * @param {Object} value The value to modify. - * @param {RegExp|string} pattern A RegExp object or literal. Can also be - * a string. It is treated as a verbatim - * string and is not interpreted as a - * regular expression. Only the first - * occurrence will be replaced. - * @param {Function|string} replacement The match or matches are replaced with - * the specified or the value returned by - * the specified function. + * @param {Object} value The value to modify. + * @param {Array} value.formats + * @param {Array} value.replacements + * @param {string} value.text + * @param {number} value.start + * @param {number} value.end + * @param {RegExp|string} pattern A RegExp object or literal. Can also be + * a string. It is treated as a verbatim + * string and is not interpreted as a + * regular expression. Only the first + * occurrence will be replaced. + * @param {Function|string} replacement The match or matches are replaced with + * the specified or the value returned by + * the specified function. * * @return {Object} A new value with replacements applied. */ diff --git a/packages/rich-text/src/split.js b/packages/rich-text/src/split.js index 1f5ebbb5b8416..650b8c426cf0d 100644 --- a/packages/rich-text/src/split.js +++ b/packages/rich-text/src/split.js @@ -15,7 +15,7 @@ import { replace } from './replace'; * @param {string} value.text * @param {number} value.start * @param {number} value.end - * @param {number|string} [string] Start index, or string at which to split. + * @param {number|string} [string] Start index, or string at which to split. * * @return {Array} An array of new values. */ diff --git a/packages/rich-text/src/store/selectors.js b/packages/rich-text/src/store/selectors.js index c76ad76d64c66..d50347cf42e04 100644 --- a/packages/rich-text/src/store/selectors.js +++ b/packages/rich-text/src/store/selectors.js @@ -20,7 +20,7 @@ export const getFormatTypes = createSelector( * Returns a format type by name. * * @param {Object} state Data state. - * @param {string} name Format type name. + * @param {string} name Format type name. * * @return {Object?} Format type. */ diff --git a/packages/rich-text/src/to-dom.js b/packages/rich-text/src/to-dom.js index a0d57617a0d0b..1c693c7335558 100644 --- a/packages/rich-text/src/to-dom.js +++ b/packages/rich-text/src/to-dom.js @@ -161,11 +161,13 @@ export function toDom( { * the `Element` tree contained by `current`. If a `multilineTag` is provided, * text separated by two new lines will be wrapped in an `Element` of that type. * - * @param {Object} $1 Named arguments. - * @param {Object} $1.value Value to apply. - * @param {HTMLElement} $1.current The live root node to apply the element tree to. - * @param {string} [$1.multilineTag] Multiline tag. - * @param {Array} [$1.multilineWrapperTags] Tags where lines can be found if nesting is possible. + * @param {Object} $1 Named arguments. + * @param {Object} $1.value Value to apply. + * @param {HTMLElement} $1.current The live root node to apply the element tree to. + * @param {string} [$1.multilineTag] Multiline tag. + * @param {Function} [$1.prepareEditableTree] + * @param {boolean} [$1.__unstableDomOnly] + * @param {string} [$1.placeholder] */ export function apply( { value, diff --git a/packages/rich-text/src/to-tree.js b/packages/rich-text/src/to-tree.js index 2cc90818e3694..a07d197dbf83b 100644 --- a/packages/rich-text/src/to-tree.js +++ b/packages/rich-text/src/to-tree.js @@ -14,14 +14,14 @@ import { * Converts a format object to information that can be used to create an element * from (type, attributes and object). * - * @param {Object} $1 Named parameters. - * @param {string} $1.type The format type. - * @param {Object} $1.attributes The format attributes. - * @param {Object} $1.unregisteredAttributes The unregistered format + * @param {Object} $1 Named parameters. + * @param {string} $1.type The format type. + * @param {Object} $1.attributes The format attributes. + * @param {Object} $1.unregisteredAttributes The unregistered format * attributes. - * @param {boolean} $1.object Wether or not it is an object + * @param {boolean} $1.object Wether or not it is an object * format. - * @param {boolean} $1.boundaryClass Wether or not to apply a boundary + * @param {boolean} $1.boundaryClass Wether or not to apply a boundary * class. * @return {Object} Information to be used for * element creation. diff --git a/packages/rich-text/src/update-formats.js b/packages/rich-text/src/update-formats.js index bc99c9ba0e5db..eea466be86297 100644 --- a/packages/rich-text/src/update-formats.js +++ b/packages/rich-text/src/update-formats.js @@ -8,11 +8,11 @@ import { isFormatEqual } from './is-format-equal'; * Efficiently updates all the formats from `start` (including) until `end` * (excluding) with the active formats. Mutates `value`. * - * @param {Object} $1 Named paramentes. - * @param {Object} $1.value Value te update. - * @param {number} $1.start Index to update from. - * @param {number} $1.end Index to update until. - * @param {Array} $1.formats Replacement formats. + * @param {Object} $1 Named paramentes. + * @param {Object} $1.value Value te update. + * @param {number} $1.start Index to update from. + * @param {number} $1.end Index to update until. + * @param {Array} $1.formats Replacement formats. * * @return {Object} Mutated value. */ diff --git a/packages/scripts/scripts/check-licenses.js b/packages/scripts/scripts/check-licenses.js index 502cfe1fae599..a081481c6bb4a 100644 --- a/packages/scripts/scripts/check-licenses.js +++ b/packages/scripts/scripts/check-licenses.js @@ -123,7 +123,7 @@ const licenseFileStrings = { * eg, "(MIT OR Zlib)". * * @param {string} allowedLicense The license that's allowed. - * @param {string} licenseType The license string to check. + * @param {string} licenseType The license string to check. * * @return {boolean} true if the licenseType matches the allowedLicense, false if it doesn't. */ diff --git a/packages/url/src/add-query-args.js b/packages/url/src/add-query-args.js index 2d48c0be5a06b..12bb6b101ccc4 100644 --- a/packages/url/src/add-query-args.js +++ b/packages/url/src/add-query-args.js @@ -8,9 +8,9 @@ import { parse, stringify } from 'qs'; * includes query arguments, the arguments are merged with (and take precedent * over) the existing set. * - * @param {string} [url=''] URL to which arguments should be appended. If omitted, + * @param {string} [url=''] URL to which arguments should be appended. If omitted, * only the resulting querystring is returned. - * @param {Object} [args] Query arguments to apply to URL. + * @param {Object} [args] Query arguments to apply to URL. * * @example * ```js diff --git a/packages/viewport/src/with-viewport-match.js b/packages/viewport/src/with-viewport-match.js index 935fdc675b4ee..04dec39657e0b 100644 --- a/packages/viewport/src/with-viewport-match.js +++ b/packages/viewport/src/with-viewport-match.js @@ -19,7 +19,7 @@ import { * * @see isViewportMatch * - * @param {Object} queries Object of prop name to viewport query. + * @param {Object} queries Object of prop name to viewport query. * * @example * diff --git a/packages/viewport/src/with-viewport-match.native.js b/packages/viewport/src/with-viewport-match.native.js index 983aa22e365f8..6ff76a86637ad 100644 --- a/packages/viewport/src/with-viewport-match.native.js +++ b/packages/viewport/src/with-viewport-match.native.js @@ -16,7 +16,7 @@ import { withSelect } from '@wordpress/data'; * * @see isViewportMatch * - * @param {Object} queries Object of prop name to viewport query. + * @param {Object} queries Object of prop name to viewport query. * * @example *