From a7e2895829c16ecd77a5ba22d84f1dee1cfb0977 Mon Sep 17 00:00:00 2001 From: Renatho De Carli Rosa Date: Wed, 9 Jun 2021 04:27:47 -0300 Subject: [PATCH] Update Eslint JSDoc package, introducing JSDoc line alignment check (#25300) * Update eslint jsdoc dependency * Add Eslint check-line-alignment rule for JSDoc validations * Disable new rule after plugin update It's temporarily disabled to allow the eslint plugin update without errors. * Remove return alignments (manually) * Update type of typeAnnotation param to a typedef The purpose of this change was readability improvement only. * Add changelog entry about jsdoc alignment * Fix jsdoc alignments Co-authored-by: Renatho De Carli Rosa --- bin/packages/build-worker.js | 12 +-- bin/packages/build.js | 15 ++-- bin/packages/watch.js | 8 +- bin/plugin/commands/changelog.js | 24 +++--- bin/plugin/commands/common.js | 2 +- bin/plugin/commands/packages.js | 20 ++--- bin/plugin/commands/performance.js | 68 +++++++-------- bin/plugin/config.js | 28 +++---- bin/plugin/lib/git.js | 20 ++--- bin/plugin/lib/utils.js | 16 ++-- package-lock.json | 77 +++++++++++++---- packages/a11y/src/index.js | 2 +- packages/a11y/src/index.native.js | 2 +- packages/annotations/src/format/annotation.js | 4 +- packages/annotations/src/store/actions.js | 4 +- packages/annotations/src/store/selectors.js | 2 +- .../src/middlewares/fetch-all-middleware.js | 2 +- packages/api-fetch/src/utils/response.js | 2 +- packages/autop/src/index.js | 24 +++--- packages/babel-plugin-makepot/index.js | 2 +- packages/block-directory/src/store/actions.js | 6 +- .../src/store/utils/has-block-type.js | 4 +- .../block-list/use-block-props/index.js | 6 +- .../block-mover/mover-description.js | 8 +- .../use-block-navigation-drop-zone.js | 12 +-- .../src/components/block-preview/index.js | 6 +- .../block-settings-menu-controls/index.js | 2 +- .../src/components/block-styles/utils.js | 4 +- .../use-transformed-patterns.js | 8 +- .../src/components/block-switcher/utils.js | 8 +- .../src/components/block-tools/index.js | 4 +- .../components/border-style-control/index.js | 8 +- .../src/components/colors/utils.js | 4 +- .../use-convert-to-group-button-props.js | 10 +-- .../font-appearance-control/index.js | 5 +- .../src/components/font-sizes/utils.js | 6 +- .../src/components/gradients/use-gradient.js | 8 +- .../use-inner-block-template-sync.js | 20 ++--- .../components/inserter-list-item/index.js | 2 +- .../inserter/hooks/use-block-types-state.js | 4 +- .../inserter/hooks/use-insertion-point.js | 18 ++-- .../inserter/reusable-blocks-tab.js | 8 +- .../src/components/inserter/search-items.js | 6 +- .../letter-spacing-control/index.js | 6 +- .../components/link-control/is-url-like.js | 3 +- .../components/link-control/search-input.js | 2 +- .../src/components/provider/use-block-sync.js | 38 ++++----- .../src/components/rich-text/index.native.js | 4 +- .../components/rich-text/use-format-types.js | 8 +- .../text-decoration-and-transform/index.js | 5 +- .../text-decoration-control/index.js | 9 +- .../text-transform-control/index.js | 9 +- .../use-block-display-information/index.js | 4 +- .../components/use-moving-animation/index.js | 2 +- .../use-no-recursive-renders/index.js | 2 +- .../src/components/use-on-block-drop/index.js | 4 +- .../writing-flow/use-multi-selection.js | 2 +- packages/block-editor/src/hooks/align.js | 24 +++--- .../block-editor/src/hooks/border-color.js | 27 +++--- .../block-editor/src/hooks/border-radius.js | 5 +- .../block-editor/src/hooks/border-style.js | 5 +- .../block-editor/src/hooks/border-width.js | 5 +- packages/block-editor/src/hooks/border.js | 14 ++-- packages/block-editor/src/hooks/color.js | 24 +++--- packages/block-editor/src/hooks/duotone.js | 26 +++--- .../block-editor/src/hooks/font-appearance.js | 24 +++--- packages/block-editor/src/hooks/font-size.js | 24 +++--- packages/block-editor/src/hooks/layout.js | 15 ++-- .../block-editor/src/hooks/letter-spacing.js | 4 +- packages/block-editor/src/hooks/margin.js | 15 ++-- packages/block-editor/src/hooks/padding.js | 10 ++- packages/block-editor/src/hooks/spacing.js | 20 +++-- packages/block-editor/src/hooks/style.js | 31 ++++--- .../block-editor/src/hooks/text-decoration.js | 10 ++- .../block-editor/src/hooks/text-transform.js | 10 ++- .../src/hooks/use-border-props.js | 11 +-- .../block-editor/src/hooks/use-color-props.js | 10 ++- packages/block-editor/src/store/actions.js | 48 +++++------ packages/block-editor/src/store/array.js | 4 +- packages/block-editor/src/store/defaults.js | 34 ++++---- packages/block-editor/src/store/reducer.js | 20 ++--- packages/block-editor/src/store/selectors.js | 83 ++++++++++--------- .../src/utils/block-variation-transforms.js | 4 +- packages/block-editor/src/utils/theme.js | 4 +- .../src/utils/transform-styles/index.js | 2 +- .../transforms/url-rewrite.js | 27 +++--- packages/block-library/src/code/utils.js | 4 +- packages/block-library/src/columns/utils.js | 8 +- packages/block-library/src/embed/util.js | 10 +-- packages/block-library/src/image/edit.js | 2 +- packages/block-library/src/image/utils.js | 6 +- .../src/legacy-widget/edit/control.js | 8 +- .../block-library/src/navigation-link/edit.js | 16 ++-- .../src/navigation/menu-items-to-blocks.js | 24 +++--- .../src/navigation/use-navigation-entities.js | 20 ++--- packages/block-library/src/query/hooks.js | 2 +- packages/block-library/src/query/utils.js | 22 ++--- .../src/table-of-contents/edit.js | 8 +- packages/block-library/src/table/state.js | 2 +- .../edit/utils/create-template-part-id.js | 2 +- packages/blocks/README.md | 2 +- packages/blocks/src/api/factory.js | 22 ++--- packages/blocks/src/api/node.js | 2 +- packages/blocks/src/api/parser.js | 6 +- .../src/api/raw-handling/paste-handler.js | 16 ++-- packages/blocks/src/api/registration.js | 80 +++++++++--------- packages/blocks/src/api/serializer.js | 8 +- packages/blocks/src/api/templates.js | 12 +-- packages/blocks/src/api/utils.js | 8 +- packages/blocks/src/api/validation/index.js | 6 +- packages/blocks/src/store/actions.js | 12 +-- packages/blocks/src/store/reducer.js | 2 +- packages/blocks/src/store/selectors.js | 14 ++-- .../src/alignment-matrix-control/utils.js | 2 +- packages/components/src/autocomplete/index.js | 22 ++--- packages/components/src/base-control/index.js | 28 +++---- packages/components/src/base-field/hook.js | 2 +- packages/components/src/color-picker/index.js | 42 +++++----- packages/components/src/color-picker/utils.js | 18 ++-- packages/components/src/dashicon/index.js | 4 +- .../components/src/dimension-control/sizes.js | 7 +- packages/components/src/disabled/index.js | 6 +- packages/components/src/draggable/index.js | 20 ++--- .../components/src/flex/flex/component.js | 2 +- packages/components/src/h-stack/utils.js | 4 +- .../higher-order/with-focus-return/index.js | 6 +- .../src/higher-order/with-notices/index.js | 8 +- .../components/src/input-control/state.js | 4 +- .../components/src/input-control/utils.js | 4 +- packages/components/src/notice/list.js | 13 +-- .../components/src/number-control/index.js | 2 +- packages/components/src/placeholder/index.js | 2 +- packages/components/src/popover/utils.js | 2 +- .../components/src/query-controls/terms.js | 2 +- .../components/src/range-control/utils.js | 2 +- .../src/resizable-box/resize-tooltip/utils.js | 32 +++---- .../components/src/scrollable/component.js | 2 +- packages/components/src/shortcut/index.js | 4 +- packages/components/src/snackbar/list.js | 13 +-- packages/components/src/surface/styles.js | 6 +- packages/components/src/text-control/index.js | 16 ++-- packages/components/src/text/utils.js | 28 +++---- packages/components/src/toolbar/index.js | 6 +- packages/components/src/truncate/utils.js | 2 +- packages/components/src/ui/card/body.js | 2 +- packages/components/src/ui/card/component.js | 2 +- packages/components/src/ui/card/footer.js | 2 +- packages/components/src/ui/card/header.js | 2 +- packages/components/src/ui/card/inner-body.js | 2 +- .../src/ui/context/context-connect.js | 10 +-- .../src/ui/context/context-system-provider.js | 6 +- .../context/get-styled-class-name-from-key.ts | 2 +- .../src/ui/context/use-context-system.js | 2 +- .../src/ui/control-group/component.js | 2 +- .../src/ui/form-group/form-group.js | 2 +- .../components/src/ui/popover/component.js | 2 +- packages/components/src/ui/popover/content.js | 2 +- .../components/src/ui/spinner/component.js | 6 +- .../components/src/ui/tooltip/component.js | 2 +- packages/components/src/ui/tooltip/content.js | 2 +- packages/components/src/ui/utils/colors.js | 2 +- .../src/ui/utils/create-component.tsx | 10 +-- .../src/ui/utils/get-valid-children.ts | 2 +- .../src/ui/utils/use-instance-id.js | 4 +- packages/components/src/unit-control/index.js | 2 +- packages/components/src/unit-control/utils.js | 14 ++-- packages/components/src/utils/browsers.js | 8 +- packages/components/src/utils/colors.js | 2 +- .../src/utils/hooks/use-controlled-state.js | 4 +- .../src/utils/hooks/use-jump-step.js | 6 +- packages/components/src/utils/math.js | 6 +- packages/components/src/utils/values.js | 4 +- .../components/src/visually-hidden/index.js | 4 +- .../components/src/visually-hidden/utils.js | 2 +- .../src/higher-order/if-condition/index.tsx | 2 +- .../higher-order/with-global-events/index.js | 10 +-- .../compose/src/hooks/use-async-list/index.ts | 6 +- .../src/hooks/use-copy-on-click/index.js | 8 +- .../src/hooks/use-copy-to-clipboard/index.js | 6 +- .../compose/src/hooks/use-debounce/index.js | 4 +- .../compose/src/hooks/use-dragging/index.js | 2 +- .../compose/src/hooks/use-drop-zone/index.js | 16 ++-- .../src/hooks/use-focus-outside/index.js | 4 +- .../hooks/use-focus-outside/index.native.js | 4 +- .../src/hooks/use-instance-id/index.js | 4 +- .../src/hooks/use-keyboard-shortcut/index.js | 16 ++-- .../compose/src/hooks/use-merge-refs/index.js | 2 +- .../compose/src/hooks/use-ref-effect/index.ts | 4 +- .../compose/src/hooks/use-throttle/index.js | 6 +- .../create-higher-order-component/index.ts | 4 +- packages/core-data/src/actions.js | 26 +++--- packages/core-data/src/batch/create-batch.js | 2 +- packages/core-data/src/entities.js | 4 +- packages/core-data/src/entity-provider.js | 6 +- .../__experimental-fetch-link-suggestions.js | 10 +-- .../__experimental-fetch-remote-url-data.js | 4 +- packages/core-data/src/locks/reducer.js | 4 +- .../core-data/src/queried-data/actions.js | 8 +- .../core-data/src/queried-data/reducer.js | 2 +- packages/core-data/src/reducer.js | 10 +-- packages/core-data/src/resolvers.js | 10 +-- packages/core-data/src/selectors.js | 44 +++++----- .../use-clear-selected-block.js | 2 +- .../customize-widgets/src/store/reducer.js | 4 +- .../components/async-mode-provider/context.js | 2 +- .../use-dispatch/use-dispatch-with-map.js | 10 +-- .../data/src/components/use-select/index.js | 28 +++---- .../data/src/components/with-select/index.js | 4 +- packages/data/src/controls.js | 12 +-- packages/data/src/factory.js | 2 +- packages/data/src/index.js | 4 +- packages/data/src/redux-store/index.js | 32 +++---- .../data/src/redux-store/metadata/actions.js | 4 +- .../data/src/redux-store/metadata/reducer.js | 4 +- .../src/redux-store/metadata/selectors.js | 2 +- packages/data/src/registry.js | 8 +- packages/date/src/index.js | 80 +++++++++--------- packages/docgen/lib/engine.js | 6 +- .../lib/get-intermediate-representation.js | 8 +- packages/docgen/lib/get-type-annotation.js | 15 ++-- packages/docgen/lib/markdown/embed.js | 4 +- .../test/fixtures/tags-function/code.js | 2 +- .../dom/src/dom/caret-range-from-point.js | 6 +- packages/dom/src/dom/clean-node-list.js | 12 +-- .../src/dom/hidden-caret-range-from-point.js | 8 +- packages/dom/src/dom/is-edge.js | 4 +- .../src/dom/place-caret-at-vertical-edge.js | 6 +- packages/dom/src/dom/remove-invalid-html.js | 4 +- packages/dom/src/dom/replace-tag.js | 4 +- packages/dom/src/phrasing-content.js | 6 +- packages/e2e-test-utils/src/create-url.js | 4 +- packages/e2e-test-utils/src/delete-theme.js | 6 +- packages/e2e-test-utils/src/install-plugin.js | 2 +- packages/e2e-test-utils/src/install-theme.js | 4 +- packages/e2e-test-utils/src/is-current-url.js | 4 +- .../src/mocks/create-embedding-matcher.js | 2 +- .../src/mocks/mock-or-transform.js | 4 +- packages/e2e-test-utils/src/posts.js | 2 +- .../src/press-key-with-modifier.js | 2 +- .../src/toggle-preferences-option.js | 4 +- .../e2e-test-utils/src/visit-admin-page.js | 2 +- packages/e2e-tests/fixtures/utils.js | 5 +- .../specs/editor/plugins/annotations.test.js | 2 +- .../experiments/blocks/navigation.test.js | 10 +-- .../experiments/navigation-editor.test.js | 2 +- .../edit-navigation/src/store/controls.js | 4 +- .../src/store/menu-items-to-blocks.js | 24 +++--- packages/edit-navigation/src/store/reducer.js | 4 +- .../edit-navigation/src/store/selectors.js | 4 +- packages/edit-navigation/src/store/utils.js | 38 ++++----- .../plugin-block-settings-menu-item.js | 2 +- .../src/components/browser-url/index.js | 6 +- .../components/editor-initialization/index.js | 2 +- .../editor-initialization/listener-hooks.js | 2 +- .../components/editor-initialization/utils.js | 11 +-- .../header/plugin-more-menu-item/index.js | 8 +- .../plugin-sidebar-more-menu-item/index.js | 4 +- .../plugin-document-setting-panel/index.js | 8 +- .../plugin-post-publish-panel/index.js | 8 +- .../sidebar/plugin-sidebar/index.js | 10 +-- packages/edit-post/src/index.native.js | 6 +- packages/edit-post/src/store/reducer.js | 12 +-- packages/edit-post/src/store/selectors.js | 27 +++--- packages/edit-post/src/utils/meta-boxes.js | 5 +- .../editor/global-styles-renderer.js | 2 +- packages/edit-site/src/store/actions.js | 12 +-- packages/edit-site/src/store/reducer.js | 10 +-- packages/edit-widgets/src/store/actions.js | 23 ++--- packages/edit-widgets/src/store/controls.js | 4 +- packages/edit-widgets/src/store/reducer.js | 11 +-- packages/edit-widgets/src/store/selectors.js | 14 ++-- packages/edit-widgets/src/store/utils.js | 4 +- .../post-publish-panel/postpublish.js | 2 +- .../src/components/post-saved-state/index.js | 10 +-- .../post-type-support-check/index.js | 12 +-- packages/editor/src/store/actions.js | 18 ++-- packages/editor/src/store/controls.js | 7 +- packages/editor/src/store/reducer.js | 10 +-- packages/editor/src/store/reducer.native.js | 12 +-- packages/editor/src/store/selectors.js | 4 +- .../editor/src/utils/media-upload/index.js | 14 ++-- packages/editor/src/utils/terms.js | 2 +- .../element/src/create-interpolate-element.js | 34 ++++---- packages/element/src/react-platform.js | 10 +-- packages/element/src/react-platform.native.js | 2 +- .../env/lib/build-docker-compose-config.js | 6 +- packages/env/lib/cache.js | 2 +- packages/env/lib/config/parse-config.js | 12 +-- packages/env/lib/config/validate-config.js | 2 +- packages/env/lib/init-config.js | 5 +- packages/env/lib/retry.js | 8 +- packages/env/lib/wordpress.js | 4 +- packages/eslint-plugin/CHANGELOG.md | 4 + packages/eslint-plugin/configs/jsdoc.js | 9 ++ packages/eslint-plugin/package.json | 2 +- .../eslint-plugin/rules/i18n-text-domain.js | 2 +- .../eslint-plugin/rules/no-unsafe-wp-apis.js | 4 +- .../utils/get-text-content-from-node.js | 2 +- packages/hooks/src/createAddHook.js | 12 +-- packages/hooks/src/createCurrentHook.js | 4 +- packages/hooks/src/createDidHook.js | 6 +- packages/hooks/src/createDoingHook.js | 8 +- packages/hooks/src/createHasHook.js | 4 +- packages/hooks/src/createRemoveHook.js | 10 +-- packages/hooks/src/createRunHook.js | 8 +- packages/hooks/src/validateHookName.js | 8 +- packages/hooks/src/validateNamespace.js | 6 +- packages/i18n/README.md | 2 +- packages/i18n/src/create-i18n.js | 35 ++++---- packages/i18n/src/default-i18n.js | 4 +- packages/i18n/src/sprintf.js | 4 +- packages/i18n/tools/pot-to-php.js | 4 +- packages/interface/src/store/selectors.js | 10 +-- packages/jest-console/src/index.js | 2 +- .../src/hooks/use-shortcut.js | 4 +- .../list-reusable-blocks/src/utils/file.js | 2 +- .../list-reusable-blocks/src/utils/import.js | 2 +- .../media-utils/src/utils/upload-media.js | 16 ++-- packages/notices/src/store/actions.js | 10 +-- packages/notices/src/store/selectors.js | 40 ++++----- packages/nux/src/store/reducer.js | 6 +- packages/react-i18n/src/index.tsx | 6 +- packages/react-native-bridge/index.js | 68 +++++++-------- .../react-native-editor/sass-transformer.js | 4 +- packages/redux-routine/src/runtime.js | 4 +- packages/reusable-blocks/src/store/actions.js | 2 +- .../reusable-blocks/src/store/controls.js | 6 +- .../reusable-blocks/src/store/selectors.js | 2 +- .../src/component/use-format-types.js | 8 +- packages/rich-text/src/create.js | 22 ++--- packages/rich-text/src/get-line-index.js | 8 +- packages/rich-text/src/indent-list-items.js | 6 +- packages/rich-text/src/is-empty.js | 2 +- .../rich-text/src/register-format-type.js | 4 +- packages/rich-text/src/replace.js | 4 +- packages/rich-text/src/store/selectors.js | 2 +- packages/rich-text/src/to-tree.js | 22 ++--- packages/rich-text/src/update-formats.js | 10 +-- packages/scripts/scripts/check-licenses.js | 2 +- packages/url/src/add-query-args.js | 6 +- packages/url/src/filter-url-for-display.js | 2 +- packages/viewport/src/with-viewport-match.js | 2 +- .../src/with-viewport-match.native.js | 2 +- packages/widgets/src/utils.js | 8 +- .../matchers/to-match-style-diff-snapshot.js | 4 +- 345 files changed, 1741 insertions(+), 1594 deletions(-) diff --git a/bin/packages/build-worker.js b/bin/packages/build-worker.js index d3b5254c32a9c..37f29a4613638 100644 --- a/bin/packages/build-worker.js +++ b/bin/packages/build-worker.js @@ -54,8 +54,9 @@ const renderSass = promisify( sass.render ); /** * Get the package name for a specified file * - * @param {string} file File name - * @return {string} Package name + * @param {string} file File name. + * + * @return {string} Package name. */ function getPackageName( file ) { return path.relative( PACKAGES_DIR, file ).split( path.sep )[ 0 ]; @@ -64,9 +65,10 @@ function getPackageName( file ) { /** * Get Build Path for a specified file. * - * @param {string} file File to build - * @param {string} buildFolder Output folder - * @return {string} Build path + * @param {string} file File to build. + * @param {string} buildFolder Output folder. + * + * @return {string} Build path. */ function getBuildPath( file, buildFolder ) { const pkgName = getPackageName( file ); diff --git a/bin/packages/build.js b/bin/packages/build.js index ff26c904fd884..bd6fd25ca25b1 100755 --- a/bin/packages/build.js +++ b/bin/packages/build.js @@ -24,8 +24,9 @@ const stylesheetEntryPoints = glob.sync( /** * Get the package name for a specified file * - * @param {string} file File name - * @return {string} Package name + * @param {string} file File name. + * + * @return {string} Package name. */ function getPackageName( file ) { return path.relative( PACKAGES_DIR, file ).split( path.sep )[ 0 ]; @@ -34,8 +35,9 @@ function getPackageName( file ) { /** * Parses all Sass import statements in a given file * - * @param {string} file File name - * @return {Array} List of Import Statements in a file + * @param {string} file File name. + * + * @return {Array} List of Import Statements in a file. */ function parseImportStatements( file ) { const fileContent = fs.readFileSync( file, 'utf8' ); @@ -58,8 +60,9 @@ function isFileImportedInStyleEntry( file, importStatements ) { * Finds all stylesheet entry points that contain import statements * that include the given file name * - * @param {string} file File name - * @return {Array} List of entry points that import the styles from the file + * @param {string} file File name. + * + * @return {Array} List of entry points that import the styles from the file. */ function findStyleEntriesThatImportFile( file ) { const entriesWithImport = stylesheetEntryPoints.reduce( diff --git a/bin/packages/watch.js b/bin/packages/watch.js index c0e8ca1586dae..6ca600a994cff 100644 --- a/bin/packages/watch.js +++ b/bin/packages/watch.js @@ -125,8 +125,8 @@ function getBuildFile( srcFile ) { /** * Adds a build file to the set of files that should be rebuilt. * - * @param {'update'} event The event name - * @param {string} filename + * @param {'update'} event The event name + * @param {string} filename */ function updateBuildFile( event, filename ) { if ( exists( filename ) ) { @@ -147,8 +147,8 @@ function updateBuildFile( event, filename ) { * Removes a build file from the build folder * (usually triggered the associated source file was deleted) * - * @param {'remove'} event The event name - * @param {string} filename + * @param {'remove'} event The event name + * @param {string} filename */ function removeBuildFile( event, filename ) { const buildFile = getBuildFile( filename ); diff --git a/bin/plugin/commands/changelog.js b/bin/plugin/commands/changelog.js index 0c2af1242a156..11d962def0649 100644 --- a/bin/plugin/commands/changelog.js +++ b/bin/plugin/commands/changelog.js @@ -27,19 +27,19 @@ const manifest = require( '../../../package.json' ); /** * @typedef WPChangelogCommandOptions * - * @property {string=} milestone Optional Milestone title. - * @property {string=} token Optional personal access token. - * @property {boolean=} unreleased Optional flag to only include issues that haven't been part of a release yet. + * @property {string=} milestone Optional Milestone title. + * @property {string=} token Optional personal access token. + * @property {boolean=} unreleased Optional flag to only include issues that haven't been part of a release yet. */ /** * @typedef WPChangelogSettings * - * @property {string} owner Repository owner. - * @property {string} repo Repository name. - * @property {string=} token Optional personal access token. - * @property {string} milestone Milestone title. - * @property {boolean=} unreleased Only include issues that have been closed since the milestone's latest release. + * @property {string} owner Repository owner. + * @property {string} repo Repository name. + * @property {string=} token Optional personal access token. + * @property {string} milestone Milestone title. + * @property {boolean=} unreleased Only include issues that have been closed since the milestone's latest release. */ /** @@ -386,10 +386,10 @@ function getEntry( issue ) { /** * Returns the latest release for a given series * - * @param {GitHub} octokit Initialized Octokit REST client. - * @param {string} owner Repository owner. - * @param {string} repo Repository name. - * @param {string} series Gutenberg release series (e.g. '6.7' or '9.8'). + * @param {GitHub} octokit Initialized Octokit REST client. + * @param {string} owner Repository owner. + * @param {string} repo Repository name. + * @param {string} series Gutenberg release series (e.g. '6.7' or '9.8'). * * @return {Promise} Promise resolving to pull * requests for the given diff --git a/bin/plugin/commands/common.js b/bin/plugin/commands/common.js index 4f3e0bb065243..c9a3eda27c54d 100644 --- a/bin/plugin/commands/common.js +++ b/bin/plugin/commands/common.js @@ -76,7 +76,7 @@ function findReleaseBranchName( packageJsonPath ) { * Calculates version bump for the packages based on the content * from the provided CHANGELOG file split into individual lines. * - * @param {string[]} lines Changelog content split into lines. + * @param {string[]} lines Changelog content split into lines. * @param {('patch'|'minor'|'major')} [minimumVersionBump] Minimum version bump for the package. * Defaults to `patch`. * diff --git a/bin/plugin/commands/packages.js b/bin/plugin/commands/packages.js index d60e7c383e840..532366b1329c8 100644 --- a/bin/plugin/commands/packages.js +++ b/bin/plugin/commands/packages.js @@ -32,9 +32,9 @@ const git = require( '../lib/git' ); * Checks out the WordPress release branch and syncs it with the changes from * the last plugin release. * - * @param {string} gitWorkingDirectoryPath Git working directory path. - * @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 {boolean} isPrerelease Whether the package version to publish is a prerelease. + * @param {string} abortMessage Abort Message. * * @return {Promise} WordPress release branch. */ @@ -97,10 +97,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 {SemVer} 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 {SemVer} 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,9 +274,9 @@ async function runPushGitChangesStep( /** * Publishes all changed packages to npm. * - * @param {string} gitWorkingDirectoryPath Git working directory path. - * @param {SemVer} minimumVersionBump Minimum version bump for the packages. - * @param {boolean} isPrerelease Whether the package version to publish is a prerelease. + * @param {string} gitWorkingDirectoryPath Git working directory path. + * @param {SemVer} minimumVersionBump Minimum version bump for the packages. + * @param {boolean} isPrerelease Whether the package version to publish is a prerelease. */ async function publishPackagesToNpm( gitWorkingDirectoryPath, diff --git a/bin/plugin/commands/performance.js b/bin/plugin/commands/performance.js index c572694d338bd..4f5f572774e33 100644 --- a/bin/plugin/commands/performance.js +++ b/bin/plugin/commands/performance.js @@ -29,46 +29,46 @@ 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[]} inserterOpen Average time to open global inserter. - * @property {number[]} inserterHover Average time to move mouse between two block item in the inserter. + * @property {number[]} load Load Time. + * @property {number[]} type Average type time. + * @property {number[]} focus Average block selection time. + * @property {number[]} inserterOpen Average time to open global inserter. + * @property {number[]} inserterHover Average time to move mouse between two block item in the inserter. */ /** * @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} inserterOpen Average time to open global inserter. - * @property {number} minInserterOpen Min time to open global inserter. - * @property {number} maxInserterOpen Max time to open global inserter. - * @property {number} inserterHover Average time to move mouse between two block item in the inserter. - * @property {number} minInserterHover Min time to move mouse between two block item in the inserter. - * @property {number} maxInserterHover Max time to move mouse between two block item in the inserter. + * @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} inserterOpen Average time to open global inserter. + * @property {number} minInserterOpen Min time to open global inserter. + * @property {number} maxInserterOpen Max time to open global inserter. + * @property {number} inserterHover Average time to move mouse between two block item in the inserter. + * @property {number} minInserterHover Min time to move mouse between two block item in the inserter. + * @property {number} maxInserterHover Max time to move mouse between two block item in the inserter. */ /** * @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=} inserterOpen Average time to open global inserter. - * @property {string=} minInserterOpen Min time to open global inserter. - * @property {string=} maxInserterOpen Max time to open global inserter. - * @property {string=} inserterHover Average time to move mouse between two block item in the inserter. - * @property {string=} minInserterHover Min time to move mouse between two block item in the inserter. - * @property {string=} maxInserterHover Max time to move mouse between two block item in the inserter. + * @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=} inserterOpen Average time to open global inserter. + * @property {string=} minInserterOpen Min time to open global inserter. + * @property {string=} maxInserterOpen Max time to open global inserter. + * @property {string=} inserterHover Average time to move mouse between two block item in the inserter. + * @property {string=} minInserterHover Min time to move mouse between two block item in the inserter. + * @property {string=} maxInserterHover Max time to move mouse between two block item in the inserter. */ /** @@ -137,8 +137,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 @@ -208,7 +208,7 @@ async function runTestSuite( testSuite, performanceTestDirectory ) { * Runs the performances tests on an array of branches and output the result. * * @param {string[]} branches Branches to compare - * @param {WPPerformanceCommandOptions} options Command options. + * @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/config.js b/bin/plugin/config.js index f045c10fdce34..678599e0efaa7 100644 --- a/bin/plugin/config.js +++ b/bin/plugin/config.js @@ -3,21 +3,21 @@ 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 - * 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} githubRepositoryURL GitHub Repository URL. + * @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} githubRepositoryURL GitHub Repository URL. * @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 52bb8118830df..64b4c532b6c62 100644 --- a/bin/plugin/lib/git.js +++ b/bin/plugin/lib/git.js @@ -29,9 +29,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 */ @@ -48,7 +48,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 ); @@ -59,7 +59,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 ); @@ -71,7 +71,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 ); @@ -82,7 +82,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 ); @@ -113,7 +113,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, @@ -129,7 +129,7 @@ async function resetLocalBranchAgainstOrigin( * Cherry-picks a commit into trunk * * @param {string} gitWorkingDirectoryPath Local repository path. - * @param {string} commitHash Branch Name + * @param {string} commitHash Branch Name */ async function cherrypickCommitIntoBranch( gitWorkingDirectoryPath, @@ -144,7 +144,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/package-lock.json b/package-lock.json index af6a1eabcde74..52a6e0e2bd3ca 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1704,6 +1704,34 @@ "resolved": "https://registry.npmjs.org/@emotion/weak-memoize/-/weak-memoize-0.2.5.tgz", "integrity": "sha512-6U71C2Wp7r5XtFtQzYrW5iKFT67OixrSxjI4MptCHzdSVlgabczzqLe0ZSgnub/5Kp4hSbpDB1tMytZY9pwxxA==" }, + "@es-joy/jsdoccomment": { + "version": "0.4.4", + "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.4.4.tgz", + "integrity": "sha512-ua4qDt9dQb4qt5OI38eCZcQZYE5Bq3P0GzgvDARdT8Lt0mAUpxKTPy8JGGqEvF77tG1irKDZ3WreeezEa3P43w==", + "dev": true, + "requires": { + "comment-parser": "^1.1.5", + "esquery": "^1.4.0", + "jsdoctypeparser": "^9.0.0" + }, + "dependencies": { + "esquery": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/esquery/-/esquery-1.4.0.tgz", + "integrity": "sha512-cCDispWt5vHHtwMY2YrAQ4ibFkAL8RbH5YGBnZBc90MolvvfkkQcJro/aZiAQUlQ3qgrYS6D6v8Gc5G5CQsc9w==", + "dev": true, + "requires": { + "estraverse": "^5.1.0" + } + }, + "estraverse": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/estraverse/-/estraverse-5.2.0.tgz", + "integrity": "sha512-BxbNGGNm0RyRYvUdHpIwv9IWzeM9XClbOxwoATuFdOE7ZE6wHL+HQ5T8hoPM+zHvmKzzsEqhgy0GrQ5X13afiQ==", + "dev": true + } + } + }, "@eslint/eslintrc": { "version": "0.2.2", "resolved": "https://registry.npmjs.org/@eslint/eslintrc/-/eslintrc-0.2.2.tgz", @@ -13795,7 +13823,7 @@ "eslint-config-prettier": "^7.1.0", "eslint-plugin-import": "^2.22.1", "eslint-plugin-jest": "^24.1.3", - "eslint-plugin-jsdoc": "^30.7.13", + "eslint-plugin-jsdoc": "^34.1.0", "eslint-plugin-jsx-a11y": "^6.4.1", "eslint-plugin-prettier": "^3.3.0", "eslint-plugin-react": "^7.22.0", @@ -25776,9 +25804,9 @@ "dev": true }, "comment-parser": { - "version": "0.7.6", - "resolved": "https://registry.npmjs.org/comment-parser/-/comment-parser-0.7.6.tgz", - "integrity": "sha512-GKNxVA7/iuTnAqGADlTWX4tkhzxZKXp5fLJqKTlQLHkE65XDUKutZ3BHaJC5IGcper2tT3QRD1xr4o3jNpgXXg==", + "version": "1.1.5", + "resolved": "https://registry.npmjs.org/comment-parser/-/comment-parser-1.1.5.tgz", + "integrity": "sha512-RePCE4leIhBlmrqiYTvaqEeGYg7qpSl4etaIabKtdOQVi+mSTIBBklGUwIr79GXYnl3LpMwmDw4KeR2stNc6FA==", "dev": true }, "commondir": { @@ -30179,17 +30207,19 @@ } }, "eslint-plugin-jsdoc": { - "version": "30.7.13", - "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-30.7.13.tgz", - "integrity": "sha512-YM4WIsmurrp0rHX6XiXQppqKB8Ne5ATiZLJe2+/fkp9l9ExXFr43BbAbjZaVrpCT+tuPYOZ8k1MICARHnURUNQ==", + "version": "34.1.0", + "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-34.1.0.tgz", + "integrity": "sha512-7uk6vD92LCGBLwl7imvf7YzZrMbLmHZVSULBJClZpYTNdTpPXOtuPNKDi8nLcXYtZf3UopNs5qR7coapBSaUtw==", "dev": true, "requires": { - "comment-parser": "^0.7.6", + "@es-joy/jsdoccomment": "^0.4.4", + "comment-parser": "1.1.5", "debug": "^4.3.1", + "esquery": "^1.4.0", "jsdoctypeparser": "^9.0.0", - "lodash": "^4.17.20", + "lodash": "^4.17.21", "regextras": "^0.7.1", - "semver": "^7.3.4", + "semver": "^7.3.5", "spdx-expression-parse": "^3.0.1" }, "dependencies": { @@ -30202,10 +30232,25 @@ "ms": "2.1.2" } }, + "esquery": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/esquery/-/esquery-1.4.0.tgz", + "integrity": "sha512-cCDispWt5vHHtwMY2YrAQ4ibFkAL8RbH5YGBnZBc90MolvvfkkQcJro/aZiAQUlQ3qgrYS6D6v8Gc5G5CQsc9w==", + "dev": true, + "requires": { + "estraverse": "^5.1.0" + } + }, + "estraverse": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/estraverse/-/estraverse-5.2.0.tgz", + "integrity": "sha512-BxbNGGNm0RyRYvUdHpIwv9IWzeM9XClbOxwoATuFdOE7ZE6wHL+HQ5T8hoPM+zHvmKzzsEqhgy0GrQ5X13afiQ==", + "dev": true + }, "lodash": { - "version": "4.17.20", - "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.20.tgz", - "integrity": "sha512-PlhdFcillOINfeV7Ni6oF1TAEayyZBoZ8bcshTHqOYJYlrqzRK5hagpagky5o4HfCzzd1TRkXPMFq6cKk9rGmA==", + "version": "4.17.21", + "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz", + "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==", "dev": true }, "lru-cache": { @@ -30224,9 +30269,9 @@ "dev": true }, "semver": { - "version": "7.3.4", - "resolved": "https://registry.npmjs.org/semver/-/semver-7.3.4.tgz", - "integrity": "sha512-tCfb2WLjqFAtXn4KEdxIhalnRtoKFN7nAwj0B3ZXCbQloV2tq5eDbcTmT68JJD3nRJq24/XgxtQKFIpQdtvmVw==", + "version": "7.3.5", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.3.5.tgz", + "integrity": "sha512-PoeGJYh8HK4BTO/a9Tf6ZG3veo/A7ZVsYrSA6J8ny9nb3B1VrpkuN+z9OE5wfE5p6H4LchYZsegiQgbJD94ZFQ==", "dev": true, "requires": { "lru-cache": "^6.0.0" 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 dd0d618f9c678..c980508afacf9 100644 --- a/packages/annotations/src/format/annotation.js +++ b/packages/annotations/src/format/annotation.js @@ -15,8 +15,8 @@ import { STORE_NAME } from '../store/constants'; /** * 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/api-fetch/src/middlewares/fetch-all-middleware.js b/packages/api-fetch/src/middlewares/fetch-all-middleware.js index 851829f64a18b..30834353fde81 100644 --- a/packages/api-fetch/src/middlewares/fetch-all-middleware.js +++ b/packages/api-fetch/src/middlewares/fetch-all-middleware.js @@ -12,7 +12,7 @@ import apiFetch from '..'; * Apply query arguments to both URL and Path, whichever is present. * * @param {import('../types').APIFetchOptions} props - * @param {Record} queryArgs + * @param {Record} queryArgs * @return {import('../types').APIFetchOptions} The request with the modified query args */ const modifyQuery = ( { path, url, ...options }, queryArgs ) => ( { diff --git a/packages/api-fetch/src/utils/response.js b/packages/api-fetch/src/utils/response.js index 0a6ce48da900f..b5be8009fd1ac 100644 --- a/packages/api-fetch/src/utils/response.js +++ b/packages/api-fetch/src/utils/response.js @@ -66,7 +66,7 @@ export const parseResponseAndNormalizeError = ( * Parses a response, throwing an error if parsing the response fails. * * @param {Response} response - * @param {boolean} shouldParseResponse + * @param {boolean} shouldParseResponse * @return {Promise} Parsed response. */ export function parseAndThrowError( response, shouldParseResponse = true ) { diff --git a/packages/autop/src/index.js b/packages/autop/src/index.js index 47e43b0389f95..596a028f46164 100644 --- a/packages/autop/src/index.js +++ b/packages/autop/src/index.js @@ -51,8 +51,9 @@ const htmlSplitRegex = ( () => { /** * Separate HTML elements and comments from the text. * - * @param {string} input The text which has to be formatted. - * @return {string[]} The formatted text. + * @param {string} input The text which has to be formatted. + * + * @return {string[]} The formatted text. */ function htmlSplit( input ) { const parts = []; @@ -81,9 +82,10 @@ 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', …}. - * @return {string} The formatted text. + * @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 ) { // Find all elements. @@ -123,9 +125,9 @@ 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- - * breaks after paragraphing. Default true. + * @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 *```js @@ -133,7 +135,7 @@ function replaceInHtmlTags( haystack, replacePairs ) { * autop( 'my text' ); // "

my text

" * ``` * - * @return {string} Text which has been converted into paragraph tags. + * @return {string} Text which has been converted into paragraph tags. */ export function autop( text, br = true ) { const preTags = []; @@ -328,7 +330,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 @@ -336,7 +338,7 @@ export function autop( text, br = true ) { * removep( '

    my text

    ' ); // "my text" * ``` * - * @return {string} The content with stripped paragraph tags. + * @return {string} The content with stripped paragraph tags. */ export function removep( html ) { const blocklist = diff --git a/packages/babel-plugin-makepot/index.js b/packages/babel-plugin-makepot/index.js index be42cb07b735e..80fcccf623a56 100644 --- a/packages/babel-plugin-makepot/index.js +++ b/packages/babel-plugin-makepot/index.js @@ -117,7 +117,7 @@ function getNodeAsString( node ) { * * @param {Object} path Traversal path. * @param {number} _originalNodeLine Private: In recursion, line number of - * the original node passed. + * the original node passed. * * @return {?string} Extracted comment. */ diff --git a/packages/block-directory/src/store/actions.js b/packages/block-directory/src/store/actions.js index e6b4867c930f3..d2ca508c0c012 100644 --- a/packages/block-directory/src/store/actions.js +++ b/packages/block-directory/src/store/actions.js @@ -202,7 +202,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. @@ -218,8 +218,8 @@ export function setIsInstalling( blockId, isInstalling ) { /** * Sets an error notice to be displayed to the user for a given block. * - * @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/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/components/block-list/use-block-props/index.js b/packages/block-editor/src/components/block-list/use-block-props/index.js index 4c4c5a6612ad9..b7449439e7234 100644 --- a/packages/block-editor/src/components/block-list/use-block-props/index.js +++ b/packages/block-editor/src/components/block-list/use-block-props/index.js @@ -50,9 +50,9 @@ const BLOCK_ANIMATION_THRESHOLD = 200; * also pass any other props through this hook, and they will be merged and * returned. * - * @param {Object} props Optional. Props to pass to the element. Must contain - * the ref if one is defined. - * @param {Object} options Options for internal use only. + * @param {Object} props Optional. Props to pass to the element. Must contain + * the ref if one is defined. + * @param {Object} options Options for internal use only. * @param {boolean} options.__unstableIsHtml * * @return {Object} Props to pass to the element to mark as a block. 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 c84a99469980f..58bfb347193ca 100644 --- a/packages/block-editor/src/components/block-mover/mover-description.js +++ b/packages/block-editor/src/components/block-mover/mover-description.js @@ -8,14 +8,14 @@ import { __, _n, sprintf, isRTL } from '@wordpress/i18n'; * * @param {number} selectedCount Number of blocks selected. * @param {string} type Block type - in the case of a single block, should - * define its 'type'. I.e. 'Text', 'Heading', 'Image' etc. + * define its 'type'. I.e. 'Text', 'Heading', 'Image' etc. * @param {number} firstIndex The index (position - 1) of the first block selected. * @param {boolean} isFirst This is the first block. * @param {boolean} isLast This is the last block. * @param {number} dir Direction of movement (> 0 is considered to be going - * down, < 0 is up). + * down, < 0 is up). * @param {string} orientation The orientation of the block movers, vertical or - * horizontal. + * horizontal. * * @return {string} Label for the block movement controls. */ @@ -222,7 +222,7 @@ export function getBlockMoverDescription( * @param {boolean} isFirst This is the first block. * @param {boolean} isLast This is the last block. * @param {number} dir Direction of movement (> 0 is considered to be going - * down, < 0 is up). + * down, < 0 is up). * * @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 a7fb9dc611251..94b1e938e9a37 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 @@ -41,11 +41,11 @@ import { store as blockEditorStore } from '../../store'; * 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. - * 'inside' refers to nesting as an inner block. + * @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. */ /** @@ -88,7 +88,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 dfec2f64fab28..cea2e8ee9b62c 100644 --- a/packages/block-editor/src/components/block-preview/index.js +++ b/packages/block-editor/src/components/block-preview/index.js @@ -56,9 +56,9 @@ export function BlockPreview( { * * @see https://github.com/WordPress/gutenberg/blob/HEAD/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-settings-menu-controls/index.js b/packages/block-editor/src/components/block-settings-menu-controls/index.js index 4279b307f7e80..81246c583d28d 100644 --- a/packages/block-editor/src/components/block-settings-menu-controls/index.js +++ b/packages/block-editor/src/components/block-settings-menu-controls/index.js @@ -67,7 +67,7 @@ const BlockSettingsMenuControlsSlot = ( { fillProps, clientIds = null } ) => { /** * @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-settings-menu-controls/README.md * - * @param {Object} props Fill props. + * @param {Object} props Fill props. * @return {WPElement} Element. */ function BlockSettingsMenuControls( { ...props } ) { 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/block-switcher/use-transformed-patterns.js b/packages/block-editor/src/components/block-switcher/use-transformed-patterns.js index 7f8c956ea6988..cc38cb4b53f65 100644 --- a/packages/block-editor/src/components/block-switcher/use-transformed-patterns.js +++ b/packages/block-editor/src/components/block-switcher/use-transformed-patterns.js @@ -14,7 +14,7 @@ import { getMatchingBlockByName, getRetainedBlockAttributes } from './utils'; * which block type's attributes to retain and prioritize * them in the merging of the attributes. * - * @param {WPBlock} match The matched block. + * @param {WPBlock} match The matched block. * @param {WPBlock} selectedBlock The selected block. * @return {void} */ @@ -36,7 +36,7 @@ export const transformMatchingBlock = ( match, selectedBlock ) => { * If not all selected blocks are matched, return nothing. * * @param {WPBlock[]} selectedBlocks The selected blocks. - * @param {WPBlock[]} patternBlocks The pattern's blocks. + * @param {WPBlock[]} patternBlocks The pattern's blocks. * @return {WPBlock[]|void} The transformed pattern's blocks or undefined if not all selected blocks have been matched. */ export const getPatternTransformedBlocks = ( @@ -88,8 +88,8 @@ export const getPatternTransformedBlocks = ( * The transformed pattern's blocks are set to a new pattern * property `transformedBlocks`. * - * @param {WPBlockPattern[]} patterns Patterns from state. - * @param {WPBlock[]} selectedBlocks The currently selected blocks. + * @param {WPBlockPattern[]} patterns Patterns from state. + * @param {WPBlock[]} selectedBlocks The currently selected blocks. * @return {TransformedBlockPattern[]} Returns the eligible matched patterns with all the selected blocks. */ // TODO tests diff --git a/packages/block-editor/src/components/block-switcher/utils.js b/packages/block-editor/src/components/block-switcher/utils.js index 2004f1d65172b..46888a5d15fbc 100644 --- a/packages/block-editor/src/components/block-switcher/utils.js +++ b/packages/block-editor/src/components/block-switcher/utils.js @@ -9,9 +9,9 @@ import { __experimentalGetBlockAttributesNamesByRole as getBlockAttributesNamesB * of the matched block (it could be an InnerBlock). * If no match is found return nothing. * - * @param {WPBlock} block The block to try to find a match. - * @param {string} selectedBlockName The block's name to use for matching condition. - * @param {Set} consumedBlocks A set holding the previously matched/consumed blocks. + * @param {WPBlock} block The block to try to find a match. + * @param {string} selectedBlockName The block's name to use for matching condition. + * @param {Set} consumedBlocks A set holding the previously matched/consumed blocks. * * @return {WPBlock?} The matched block if found or nothing(`undefined`). */ @@ -41,7 +41,7 @@ export const getMatchingBlockByName = ( * attributes. If no `role:content` attributes exist, * return selected block's attributes. * - * @param {string} name Block type's namespaced name. + * @param {string} name Block type's namespaced name. * @param {Object} attributes Selected block's attributes. * @return {Object} The block's attributes to retain. */ diff --git a/packages/block-editor/src/components/block-tools/index.js b/packages/block-editor/src/components/block-tools/index.js index ad1e0fcd956c1..04302c68e173f 100644 --- a/packages/block-editor/src/components/block-tools/index.js +++ b/packages/block-editor/src/components/block-tools/index.js @@ -19,8 +19,8 @@ import { usePopoverScroll } from './use-popover-scroll'; * insertion point and a slot for the inline rich text toolbar). Must be wrapped * around the block content and editor styles wrapper or iframe. * - * @param {Object} $0 Props. - * @param {Object} $0.children The block content and style container. + * @param {Object} $0 Props. + * @param {Object} $0.children The block content and style container. * @param {Object} $0.__unstableContentRef Ref holding the content scroll container. */ export default function BlockTools( { children, __unstableContentRef } ) { diff --git a/packages/block-editor/src/components/border-style-control/index.js b/packages/block-editor/src/components/border-style-control/index.js index ee2ad2482cd3c..c07e3962438e2 100644 --- a/packages/block-editor/src/components/border-style-control/index.js +++ b/packages/block-editor/src/components/border-style-control/index.js @@ -37,11 +37,11 @@ const BORDER_STYLES = [ /** * Control to display border style options. * - * @param {Object} props Component props. - * @param {Object} props.onChange Handler for changing border style selection. - * @param {Object} props.value Currently selected border style value. + * @param {Object} props Component props. + * @param {Object} props.onChange Handler for changing border style selection. + * @param {Object} props.value Currently selected border style value. * - * @return {WPElement} Custom border style select control. + * @return {WPElement} Custom border style select control. */ export default function BorderStyleControl( { onChange, value } ) { const style = BORDER_STYLES.find( ( option ) => option.key === value ); diff --git a/packages/block-editor/src/components/colors/utils.js b/packages/block-editor/src/components/colors/utils.js index 00dcd5ea5b1f0..98b00b62411f0 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/convert-to-group-buttons/use-convert-to-group-button-props.js b/packages/block-editor/src/components/convert-to-group-buttons/use-convert-to-group-button-props.js index ebbc162ad9c9c..07b2e275e3975 100644 --- a/packages/block-editor/src/components/convert-to-group-buttons/use-convert-to-group-button-props.js +++ b/packages/block-editor/src/components/convert-to-group-buttons/use-convert-to-group-button-props.js @@ -13,11 +13,11 @@ import { store as blockEditorStore } from '../../store'; * Contains the properties `ConvertToGroupButton` component needs. * * @typedef {Object} ConvertToGroupButtonProps - * @property {string[]} clientIds An array of the selected client ids. - * @property {boolean} isGroupable Indicates if the selected blocks can be grouped. - * @property {boolean} isUngroupable Indicates if the selected blocks can be ungrouped. - * @property {WPBlock[]} blocksSelection An array of the selected blocks. - * @property {string} groupingBlockName The name of block used for handling grouping interactions. + * @property {string[]} clientIds An array of the selected client ids. + * @property {boolean} isGroupable Indicates if the selected blocks can be grouped. + * @property {boolean} isUngroupable Indicates if the selected blocks can be ungrouped. + * @property {WPBlock[]} blocksSelection An array of the selected blocks. + * @property {string} groupingBlockName The name of block used for handling grouping interactions. */ /** diff --git a/packages/block-editor/src/components/font-appearance-control/index.js b/packages/block-editor/src/components/font-appearance-control/index.js index 54fd0f977224b..224f9361d32f2 100644 --- a/packages/block-editor/src/components/font-appearance-control/index.js +++ b/packages/block-editor/src/components/font-appearance-control/index.js @@ -58,8 +58,9 @@ const FONT_WEIGHTS = [ /** * Control to display unified font style and weight options. * - * @param {Object} props Component props. - * @return {WPElement} Font appearance control. + * @param {Object} props Component props. + * + * @return {WPElement} Font appearance control. */ export default function FontAppearanceControl( props ) { const { diff --git a/packages/block-editor/src/components/font-sizes/utils.js b/packages/block-editor/src/components/font-sizes/utils.js index 8284dbe981abd..80782f1753ba2 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 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 736658c823d81..dcd8b36ff7db3 100644 --- a/packages/block-editor/src/components/gradients/use-gradient.js +++ b/packages/block-editor/src/components/gradients/use-gradient.js @@ -28,8 +28,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. */ @@ -49,8 +49,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 cc7d47e75bb04..de9d3fa9b5849 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 @@ -22,17 +22,17 @@ import { store as blockEditorStore } from '../../store'; * 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 - * 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 - * the inner blocks will not be synchronized with - * the given 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 + * 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 + * the inner blocks will not be synchronized with + * the given template. * @param {boolean} templateInsertUpdatesSelection Whether or not to update the - * block-editor selection state when inner blocks - * are replaced after template synchronization. + * block-editor selection state when inner blocks + * are replaced after template synchronization. */ export default function useInnerBlockTemplateSync( clientId, diff --git a/packages/block-editor/src/components/inserter-list-item/index.js b/packages/block-editor/src/components/inserter-list-item/index.js index 5a13c27c8616f..9fdf42f91eeb9 100644 --- a/packages/block-editor/src/components/inserter-list-item/index.js +++ b/packages/block-editor/src/components/inserter-list-item/index.js @@ -23,7 +23,7 @@ import InserterDraggableBlocks from '../inserter-draggable-blocks'; /** * 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/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 1184fe72f75a5..0b7c8040af8d3 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 @@ -17,8 +17,8 @@ import { store as blockEditorStore } from '../../../store'; /** * 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/inserter/hooks/use-insertion-point.js b/packages/block-editor/src/components/inserter/hooks/use-insertion-point.js index fec66c1ef0913..ef3301148b6fe 100644 --- a/packages/block-editor/src/components/inserter/hooks/use-insertion-point.js +++ b/packages/block-editor/src/components/inserter/hooks/use-insertion-point.js @@ -20,15 +20,15 @@ import { store as blockEditorStore } from '../../../store'; /** * @typedef WPInserterConfig * - * @property {string=} rootClientId If set, insertion will be into the - * block with this ID. - * @property {number=} insertionIndex If set, insertion will be into this - * explicit position. - * @property {string=} clientId If set, insertion will be after the - * block with this ID. - * @property {boolean=} isAppender Whether the inserter is an appender - * or not. - * @property {Function=} onSelect Called after insertion. + * @property {string=} rootClientId If set, insertion will be into the + * block with this ID. + * @property {number=} insertionIndex If set, insertion will be into this + * explicit position. + * @property {string=} clientId If set, insertion will be after the + * block with this ID. + * @property {boolean=} isAppender Whether the inserter is an appender + * or not. + * @property {Function=} onSelect Called after insertion. */ /** diff --git a/packages/block-editor/src/components/inserter/reusable-blocks-tab.js b/packages/block-editor/src/components/inserter/reusable-blocks-tab.js index 3afb07cd9a8bb..2fbd5e49ae8c0 100644 --- a/packages/block-editor/src/components/inserter/reusable-blocks-tab.js +++ b/packages/block-editor/src/components/inserter/reusable-blocks-tab.js @@ -43,10 +43,10 @@ function ReusableBlocksList( { onHover, onInsert, rootClientId } ) { /** * List of reusable blocks shown in the "Reusable" tab of the inserter. * - * @param {Object} props Component props. - * @param {?string} props.rootClientId Client id of block to insert into. - * @param {Function} props.onInsert Callback to run when item is inserted. - * @param {Function} props.onHover Callback to run when item is hovered. + * @param {Object} props Component props. + * @param {?string} props.rootClientId Client id of block to insert into. + * @param {Function} props.onInsert Callback to run when item is inserted. + * @param {Function} props.onHover Callback to run when item is hovered. * * @return {WPComponent} The component. */ diff --git a/packages/block-editor/src/components/inserter/search-items.js b/packages/block-editor/src/components/inserter/search-items.js index a896ba857a682..56d55de91e47f 100644 --- a/packages/block-editor/src/components/inserter/search-items.js +++ b/packages/block-editor/src/components/inserter/search-items.js @@ -82,7 +82,8 @@ export const searchBlockItems = ( * @param {Array} items Item list * @param {string} searchInput Search input. * @param {Object} config Search Config. - * @return {Array} Filtered item list. + * + * @return {Array} Filtered item list. */ export const searchItems = ( items = [], searchInput = '', config = {} ) => { const normalizedSearchTerms = getNormalizedSearchTerms( searchInput ); @@ -108,7 +109,8 @@ export const searchItems = ( items = [], searchInput = '', config = {} ) => { * @param {Object} item Item to filter. * @param {string} searchTerm Search term. * @param {Object} config Search Config. - * @return {number} Search Rank. + * + * @return {number} Search Rank. */ export function getItemSearchRank( item, searchTerm, config = {} ) { const { diff --git a/packages/block-editor/src/components/letter-spacing-control/index.js b/packages/block-editor/src/components/letter-spacing-control/index.js index 4aba5958c9f4a..b16ace3081cae 100644 --- a/packages/block-editor/src/components/letter-spacing-control/index.js +++ b/packages/block-editor/src/components/letter-spacing-control/index.js @@ -28,9 +28,9 @@ const CSS_UNITS = [ /** * Control for letter-spacing. * - * @param {Object} props Component props. - * @param {string} props.value Currently selected letter-spacing. - * @param {Function} props.onChange Handles change in letter-spacing selection. + * @param {Object} props Component props. + * @param {string} props.value Currently selected letter-spacing. + * @param {Function} props.onChange Handles change in letter-spacing selection. * @return {WPElement} Letter-spacing control. */ export default function LetterSpacingControl( { value, onChange } ) { diff --git a/packages/block-editor/src/components/link-control/is-url-like.js b/packages/block-editor/src/components/link-control/is-url-like.js index e1d2b563cfaec..fe44da9fcdbdb 100644 --- a/packages/block-editor/src/components/link-control/is-url-like.js +++ b/packages/block-editor/src/components/link-control/is-url-like.js @@ -16,7 +16,8 @@ import { isURL } from '@wordpress/url'; * creating a link it makes sense to treat it like one. * * @param {string} val the candidate for being URL-like (or not). - * @return {boolean} whether or not the value is potentially a URL. + * + * @return {boolean} whether or not the value is potentially a URL. */ export default function isURLLike( val ) { const isInternal = startsWith( val, '#' ); 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 07a6a147b335f..dbcb837498712 100644 --- a/packages/block-editor/src/components/provider/use-block-sync.js +++ b/packages/block-editor/src/components/provider/use-block-sync.js @@ -46,25 +46,25 @@ import { store as blockEditorStore } from '../../store'; * 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. - * 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 - * is used to initalize the block-editor store - * and for resetting the blocks to incoming - * changes like undo. - * @param {Object} props.selection The selection state responsible to restore the selection on undo/redo. - * @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 - * change has been made in the block-editor blocks - * for the given clientId. When this is called, - * controlling sources do not become dirty. + * @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 + * is used to initalize the block-editor store + * and for resetting the blocks to incoming + * changes like undo. + * @param {Object} props.selection The selection state responsible to restore the selection on undo/redo. + * @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 + * change has been made in the block-editor blocks + * for the given clientId. When this is called, + * controlling sources do not become dirty. */ export default function useBlockSync( { clientId = null, diff --git a/packages/block-editor/src/components/rich-text/index.native.js b/packages/block-editor/src/components/rich-text/index.native.js index af1c78d6e6d9f..5c9af75b2796f 100644 --- a/packages/block-editor/src/components/rich-text/index.native.js +++ b/packages/block-editor/src/components/rich-text/index.native.js @@ -241,8 +241,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/rich-text/use-format-types.js b/packages/block-editor/src/components/rich-text/use-format-types.js index 264ce7b8098fc..b9fb4c6862321 100644 --- a/packages/block-editor/src/components/rich-text/use-format-types.js +++ b/packages/block-editor/src/components/rich-text/use-format-types.js @@ -36,11 +36,11 @@ const interactiveContentTags = new Set( [ * This hook provides RichText with the `formatTypes` and its derived props from * experimental format type settings. * - * @param {Object} $0 Options - * @param {string} $0.clientId Block client ID. - * @param {string} $0.identifier Block attribute. + * @param {Object} $0 Options + * @param {string} $0.clientId Block client ID. + * @param {string} $0.identifier Block attribute. * @param {boolean} $0.withoutInteractiveFormatting Whether to clean the interactive formattings or not. - * @param {Array} $0.allowedFormats Allowed formats + * @param {Array} $0.allowedFormats Allowed formats */ export function useFormatTypes( { clientId, diff --git a/packages/block-editor/src/components/text-decoration-and-transform/index.js b/packages/block-editor/src/components/text-decoration-and-transform/index.js index 2d611b08b138e..0a0464420dd83 100644 --- a/packages/block-editor/src/components/text-decoration-and-transform/index.js +++ b/packages/block-editor/src/components/text-decoration-and-transform/index.js @@ -15,8 +15,9 @@ import { * so they can be laid out in a more flexible manner within the Typography * InspectorControls panel. * - * @param {Object} props Block props to be passed on to individual controls. - * @return {WPElement} Component containing text decoration or transform controls. + * @param {Object} props Block props to be passed on to individual controls. + * + * @return {WPElement} Component containing text decoration or transform controls. */ export default function TextDecorationAndTransformEdit( props ) { const decorationAvailable = ! useIsTextDecorationDisabled( props ); diff --git a/packages/block-editor/src/components/text-decoration-control/index.js b/packages/block-editor/src/components/text-decoration-control/index.js index 0385a5d6a943e..6e8695ca05081 100644 --- a/packages/block-editor/src/components/text-decoration-control/index.js +++ b/packages/block-editor/src/components/text-decoration-control/index.js @@ -21,10 +21,11 @@ const TEXT_DECORATIONS = [ /** * Control to facilitate text decoration selections. * - * @param {Object} props Component props. - * @param {string} props.value Currently selected text decoration. - * @param {Function} props.onChange Handles change in text decoration selection. - * @return {WPElement} Text decoration control. + * @param {Object} props Component props. + * @param {string} props.value Currently selected text decoration. + * @param {Function} props.onChange Handles change in text decoration selection. + * + * @return {WPElement} Text decoration control. */ export default function TextDecorationControl( { value, onChange } ) { return ( diff --git a/packages/block-editor/src/components/text-transform-control/index.js b/packages/block-editor/src/components/text-transform-control/index.js index 6aeec3101256d..262484d843a3b 100644 --- a/packages/block-editor/src/components/text-transform-control/index.js +++ b/packages/block-editor/src/components/text-transform-control/index.js @@ -30,10 +30,11 @@ const TEXT_TRANSFORMS = [ /** * Control to facilitate text transform selections. * - * @param {Object} props Component props. - * @param {string} props.value Currently selected text transform. - * @param {Function} props.onChange Handles change in text transform selection. - * @return {WPElement} Text transform control. + * @param {Object} props Component props. + * @param {string} props.value Currently selected text transform. + * @param {Function} props.onChange Handles change in text transform selection. + * + * @return {WPElement} Text transform control. */ export default function TextTransformControl( { value, onChange } ) { return ( diff --git a/packages/block-editor/src/components/use-block-display-information/index.js b/packages/block-editor/src/components/use-block-display-information/index.js index ea81142000ef7..64614344d0dcb 100644 --- a/packages/block-editor/src/components/use-block-display-information/index.js +++ b/packages/block-editor/src/components/use-block-display-information/index.js @@ -16,8 +16,8 @@ import { store as blockEditorStore } from '../../store'; * * @typedef {Object} WPBlockDisplayInformation * - * @property {string} title Human-readable block type label. - * @property {WPIcon} icon Block type icon. + * @property {string} title Human-readable block type label. + * @property {WPIcon} icon Block type icon. * @property {string} description A detailed block type description. */ 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 5c994ce0d4b94..c3c17a36498c4 100644 --- a/packages/block-editor/src/components/use-moving-animation/index.js +++ b/packages/block-editor/src/components/use-moving-animation/index.js @@ -19,7 +19,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/components/use-no-recursive-renders/index.js b/packages/block-editor/src/components/use-no-recursive-renders/index.js index 81df505674771..c5339b048330a 100644 --- a/packages/block-editor/src/components/use-no-recursive-renders/index.js +++ b/packages/block-editor/src/components/use-no-recursive-renders/index.js @@ -20,7 +20,7 @@ const RenderedRefsContext = createContext( {} ); * * @param {Object} renderedBlocks Rendered blocks grouped by block name * @param {string} blockName Name of the block. - * @param {*} uniqueId Any value that acts as a unique identifier for a block instance. + * @param {*} uniqueId Any value that acts as a unique identifier for a block instance. * * @return {Object} The list of rendered blocks grouped by block name. */ diff --git a/packages/block-editor/src/components/use-on-block-drop/index.js b/packages/block-editor/src/components/use-on-block-drop/index.js index 18ecb27abd3e0..9eef78252194b 100644 --- a/packages/block-editor/src/components/use-on-block-drop/index.js +++ b/packages/block-editor/src/components/use-on-block-drop/index.js @@ -51,8 +51,8 @@ export function parseDropEvent( event ) { /** * A function that returns an event handler function for block drop events. * - * @param {string} targetRootClientId The root client id where the block(s) will be inserted. - * @param {number} targetBlockIndex The index where the block(s) will be inserted. + * @param {string} targetRootClientId The root client id where the block(s) will be inserted. + * @param {number} targetBlockIndex The index where the block(s) will be inserted. * @param {Function} getBlockIndex A function that gets the index of a block. * @param {Function} getClientIdsOfDescendants A function that gets the client ids of descendant blocks. * @param {Function} moveBlocksToPosition A function that moves blocks. diff --git a/packages/block-editor/src/components/writing-flow/use-multi-selection.js b/packages/block-editor/src/components/writing-flow/use-multi-selection.js index 795eaf964f629..4d5f9e28415bc 100644 --- a/packages/block-editor/src/components/writing-flow/use-multi-selection.js +++ b/packages/block-editor/src/components/writing-flow/use-multi-selection.js @@ -32,7 +32,7 @@ function toggleRichText( container, toggle ) { * 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/hooks/align.js b/packages/block-editor/src/hooks/align.js index 34e1d3ffe9461..7cfd5f8b13fde 100644 --- a/packages/block-editor/src/hooks/align.js +++ b/packages/block-editor/src/hooks/align.js @@ -81,8 +81,9 @@ export function getValidAlignments( /** * Filters registered block settings, extending attributes to include `align`. * - * @param {Object} settings Original block settings - * @return {Object} Filtered block settings + * @param {Object} settings Original block settings. + * + * @return {Object} Filtered block settings. */ export function addAttribute( settings ) { // allow blocks to specify their own attribute definition with default values if needed. @@ -109,8 +110,9 @@ export function addAttribute( settings ) { * Override the default edit UI to include new toolbar controls for block * alignment, if block defines support. * - * @param {Function} BlockEdit Original component - * @return {Function} Wrapped component + * @param {Function} BlockEdit Original component. + * + * @return {Function} Wrapped component. */ export const withToolbarControls = createHigherOrderComponent( ( BlockEdit ) => ( props ) => { @@ -157,8 +159,9 @@ export const withToolbarControls = createHigherOrderComponent( /** * Override the default block element to add alignment wrapper props. * - * @param {Function} BlockListBlock Original component - * @return {Function} Wrapped component + * @param {Function} BlockListBlock Original component. + * + * @return {Function} Wrapped component. */ export const withDataAlign = createHigherOrderComponent( ( BlockListBlock ) => ( props ) => { @@ -191,10 +194,11 @@ 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 - * @return {Object} Filtered props applied to save element + * @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 ) { const { align } = attributes; diff --git a/packages/block-editor/src/hooks/border-color.js b/packages/block-editor/src/hooks/border-color.js index bcf89f31ac791..63e1941e17a2d 100644 --- a/packages/block-editor/src/hooks/border-color.js +++ b/packages/block-editor/src/hooks/border-color.js @@ -36,8 +36,9 @@ const EMPTY_ARRAY = []; * inspector controls. If they share the same block attributes it should not * matter. * - * @param {Object} props Block properties. - * @return {WPElement} Border color edit element. + * @param {Object} props Block properties. + * + * @return {WPElement} Border color edit element. */ export function BorderColorEdit( props ) { const { @@ -84,8 +85,9 @@ export function BorderColorEdit( props ) { * Filters registered block settings, extending attributes to include * `borderColor` if needed. * - * @param {Object} settings Original block settings. - * @return {Object} Updated block settings. + * @param {Object} settings Original block settings. + * + * @return {Object} Updated block settings. */ function addAttributes( settings ) { if ( ! hasBorderSupport( settings, 'color' ) ) { @@ -112,10 +114,11 @@ function addAttributes( settings ) { /** * Override props assigned to save component to inject border color. * - * @param {Object} props Additional props applied to save element. - * @param {Object} blockType Block type definition. - * @param {Object} attributes Block's attributes - * @return {Object} Filtered props to apply to save element. + * @param {Object} props Additional props applied to save element. + * @param {Object} blockType Block type definition. + * @param {Object} attributes Block's attributes. + * + * @return {Object} Filtered props to apply to save element. */ function addSaveProps( props, blockType, attributes ) { if ( @@ -145,7 +148,8 @@ function addSaveProps( props, blockType, attributes ) { * classnames to the block edit wrapper. * * @param {Object} settings Original block settings. - * @return {Object} Filtered block settings. + * + * @return {Object} Filtered block settings. */ function addEditProps( settings ) { if ( @@ -173,8 +177,9 @@ function addEditProps( settings ) { * 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 - * @return {Function} Wrapped component + * @param {Function} BlockListBlock Original component. + * + * @return {Function} Wrapped component. */ export const withBorderColorPaletteStyles = createHigherOrderComponent( ( BlockListBlock ) => ( props ) => { diff --git a/packages/block-editor/src/hooks/border-radius.js b/packages/block-editor/src/hooks/border-radius.js index a301f0570725a..6e1cc8753ebe7 100644 --- a/packages/block-editor/src/hooks/border-radius.js +++ b/packages/block-editor/src/hooks/border-radius.js @@ -16,8 +16,9 @@ const MIN_BORDER_RADIUS_VALUE = 0; /** * Inspector control panel containing the border radius related configuration. * - * @param {Object} props Block properties. - * @return {WPElement} Border radius edit element. + * @param {Object} props Block properties. + * + * @return {WPElement} Border radius edit element. */ export function BorderRadiusEdit( props ) { const { diff --git a/packages/block-editor/src/hooks/border-style.js b/packages/block-editor/src/hooks/border-style.js index 9f1b1e49b2143..feaac4c694389 100644 --- a/packages/block-editor/src/hooks/border-style.js +++ b/packages/block-editor/src/hooks/border-style.js @@ -7,8 +7,9 @@ import { cleanEmptyObject } from './utils'; /** * Inspector control for configuring border style property. * - * @param {Object} props Block properties. - * @return {WPElement} Border style edit element. + * @param {Object} props Block properties. + * + * @return {WPElement} Border style edit element. */ export const BorderStyleEdit = ( props ) => { const { diff --git a/packages/block-editor/src/hooks/border-width.js b/packages/block-editor/src/hooks/border-width.js index 341fca06fdc5b..6847c9dd9e92f 100644 --- a/packages/block-editor/src/hooks/border-width.js +++ b/packages/block-editor/src/hooks/border-width.js @@ -16,8 +16,9 @@ const MIN_BORDER_WIDTH = 0; /** * Inspector control for configuring border width property. * - * @param {Object} props Block properties. - * @return {WPElement} Border width edit element. + * @param {Object} props Block properties. + * + * @return {WPElement} Border width edit element. */ export const BorderWidthEdit = ( props ) => { const { diff --git a/packages/block-editor/src/hooks/border.js b/packages/block-editor/src/hooks/border.js index f7db904d666aa..3292da3e2efeb 100644 --- a/packages/block-editor/src/hooks/border.js +++ b/packages/block-editor/src/hooks/border.js @@ -43,7 +43,7 @@ export const CSS_UNITS = [ /** * Parses a CSS unit from a border CSS value. * - * @param {string} cssValue CSS value to parse e.g. `10px` or `1.5em`. + * @param {string} cssValue CSS value to parse e.g. `10px` or `1.5em`. * @return {string} CSS unit from provided value or default 'px'. */ export function parseUnit( cssValue ) { @@ -98,9 +98,10 @@ export function BorderPanel( props ) { /** * Determine whether there is block support for border properties. * - * @param {string} blockName Block name. - * @param {string} feature Border feature to check support for. - * @return {boolean} Whether there is support. + * @param {string} blockName Block name. + * @param {string} feature Border feature to check support for. + * + * @return {boolean} Whether there is support. */ export function hasBorderSupport( blockName, feature = 'any' ) { if ( Platform.OS !== 'web' ) { @@ -128,8 +129,9 @@ export function hasBorderSupport( blockName, feature = 'any' ) { /** * Check whether serialization of border classes and styles should be skipped. * - * @param {string|Object} blockType Block name or block type object. - * @return {boolean} Whether serialization of border properties should occur. + * @param {string|Object} blockType Block name or block type object. + * + * @return {boolean} Whether serialization of border properties should occur. */ export function shouldSkipSerialization( blockType ) { const support = getBlockSupport( blockType, BORDER_SUPPORT_KEY ); diff --git a/packages/block-editor/src/hooks/color.js b/packages/block-editor/src/hooks/color.js index f8159240a20b8..554781d057b5f 100644 --- a/packages/block-editor/src/hooks/color.js +++ b/packages/block-editor/src/hooks/color.js @@ -86,8 +86,9 @@ const hasTextColorSupport = ( blockType ) => { * Filters registered block settings, extending attributes to include * `backgroundColor` and `textColor` attribute. * - * @param {Object} settings Original block settings - * @return {Object} Filtered block settings + * @param {Object} settings Original block settings. + * + * @return {Object} Filtered block settings. */ function addAttributes( settings ) { if ( ! hasColorSupport( settings ) ) { @@ -124,10 +125,11 @@ 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 - * @return {Object} Filtered props applied to save element + * @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 ) { if ( @@ -174,8 +176,9 @@ 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 - * @return {Object} Filtered block settings + * @param {Object} settings Original block settings. + * + * @return {Object} Filtered block settings. */ export function addEditProps( settings ) { if ( @@ -381,8 +384,9 @@ 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 - * @return {Function} Wrapped component + * @param {Function} BlockListBlock Original component. + * + * @return {Function} Wrapped component. */ export const withColorPaletteStyles = createHigherOrderComponent( ( BlockListBlock ) => ( props ) => { diff --git a/packages/block-editor/src/hooks/duotone.js b/packages/block-editor/src/hooks/duotone.js index c4845b34b49f8..6e5a79766cae8 100644 --- a/packages/block-editor/src/hooks/duotone.js +++ b/packages/block-editor/src/hooks/duotone.js @@ -54,11 +54,12 @@ export function getValuesFromColors( colors = [] ) { /** * SVG and stylesheet needed for rendering the duotone filter. * - * @param {Object} props Duotone props. - * @param {string} props.selector Selector to apply the filter to. - * @param {string} props.id Unique id for this duotone filter. - * @param {Values} props.values R, G, and B values to filter with. - * @return {WPElement} Duotone element. + * @param {Object} props Duotone props. + * @param {string} props.selector Selector to apply the filter to. + * @param {string} props.id Unique id for this duotone filter. + * @param {Values} props.values R, G, and B values to filter with. + * + * @return {WPElement} Duotone element. */ function DuotoneFilter( { selector, id, values } ) { const stylesheet = ` @@ -153,8 +154,9 @@ function DuotonePanel( { attributes, setAttributes } ) { * Filters registered block settings, extending attributes to include * the `duotone` attribute. * - * @param {Object} settings Original block settings - * @return {Object} Filtered block settings + * @param {Object} settings Original block settings. + * + * @return {Object} Filtered block settings. */ function addDuotoneAttributes( settings ) { if ( ! hasBlockSupport( settings, 'color.__experimentalDuotone' ) ) { @@ -178,8 +180,9 @@ function addDuotoneAttributes( settings ) { * Override the default edit UI to include toolbar controls for duotone if the * block supports duotone. * - * @param {Function} BlockEdit Original component - * @return {Function} Wrapped component + * @param {Function} BlockEdit Original component. + * + * @return {Function} Wrapped component. */ const withDuotoneControls = createHigherOrderComponent( ( BlockEdit ) => ( props ) => { @@ -201,8 +204,9 @@ const withDuotoneControls = createHigherOrderComponent( /** * Override the default block element to include duotone styles. * - * @param {Function} BlockListBlock Original component - * @return {Function} Wrapped component + * @param {Function} BlockListBlock Original component. + * + * @return {Function} Wrapped component. */ const withDuotoneStyles = createHigherOrderComponent( ( BlockListBlock ) => ( props ) => { diff --git a/packages/block-editor/src/hooks/font-appearance.js b/packages/block-editor/src/hooks/font-appearance.js index 641985f69e484..4bb7e593a4e0a 100644 --- a/packages/block-editor/src/hooks/font-appearance.js +++ b/packages/block-editor/src/hooks/font-appearance.js @@ -23,8 +23,9 @@ export const FONT_WEIGHT_SUPPORT_KEY = 'typography.__experimentalFontWeight'; /** * Inspector control panel containing the font appearance options. * - * @param {Object} props Block properties. - * @return {WPElement} Font appearance edit element. + * @param {Object} props Block properties. + * + * @return {WPElement} Font appearance edit element. */ export function FontAppearanceEdit( props ) { const { @@ -70,9 +71,10 @@ export function FontAppearanceEdit( props ) { * Checks if font style support has been disabled either by not opting in for * support or by failing to provide preset styles. * - * @param {Object} props Block properties. - * @param {string} props.name Name for the block type. - * @return {boolean} Whether font style support has been disabled. + * @param {Object} props Block properties. + * @param {string} props.name Name for the block type. + * + * @return {boolean} Whether font style support has been disabled. */ export function useIsFontStyleDisabled( { name: blockName } = {} ) { const styleSupport = hasBlockSupport( blockName, FONT_STYLE_SUPPORT_KEY ); @@ -85,9 +87,10 @@ export function useIsFontStyleDisabled( { name: blockName } = {} ) { * Checks if font weight support has been disabled either by not opting in for * support or by failing to provide preset weights. * - * @param {Object} props Block properties. - * @param {string} props.name Name for the block type. - * @return {boolean} Whether font weight support has been disabled. + * @param {Object} props Block properties. + * @param {string} props.name Name for the block type. + * + * @return {boolean} Whether font weight support has been disabled. */ export function useIsFontWeightDisabled( { name: blockName } = {} ) { const weightSupport = hasBlockSupport( blockName, FONT_WEIGHT_SUPPORT_KEY ); @@ -99,8 +102,9 @@ export function useIsFontWeightDisabled( { name: blockName } = {} ) { /** * Checks if font appearance support has been disabled. * - * @param {Object} props Block properties. - * @return {boolean} Whether font appearance support has been disabled. + * @param {Object} props Block properties. + * + * @return {boolean} Whether font appearance support has been disabled. */ export function useIsFontAppearanceDisabled( props ) { const stylesDisabled = useIsFontStyleDisabled( props ); diff --git a/packages/block-editor/src/hooks/font-size.js b/packages/block-editor/src/hooks/font-size.js index e678f31abd48c..86624748a790b 100644 --- a/packages/block-editor/src/hooks/font-size.js +++ b/packages/block-editor/src/hooks/font-size.js @@ -24,8 +24,9 @@ export const FONT_SIZE_SUPPORT_KEY = 'typography.fontSize'; * Filters registered block settings, extending attributes to include * `fontSize` and `fontWeight` attributes. * - * @param {Object} settings Original block settings - * @return {Object} Filtered block settings + * @param {Object} settings Original block settings. + * + * @return {Object} Filtered block settings. */ function addAttributes( settings ) { if ( ! hasBlockSupport( settings, FONT_SIZE_SUPPORT_KEY ) ) { @@ -47,10 +48,11 @@ 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 - * @return {Object} Filtered props applied to save element + * @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 ) { if ( ! hasBlockSupport( blockType, FONT_SIZE_SUPPORT_KEY ) ) { @@ -79,8 +81,9 @@ 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 - * @return {Object} Filtered block settings + * @param {Object} settings Original block settings. + * + * @return {Object} Filtered block settings. */ function addEditProps( settings ) { if ( ! hasBlockSupport( settings, FONT_SIZE_SUPPORT_KEY ) ) { @@ -165,8 +168,9 @@ 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 - * @return {Function} Wrapped component + * @param {Function} BlockListBlock Original component. + * + * @return {Function} Wrapped component. */ const withFontSizeInlineStyles = createHigherOrderComponent( ( BlockListBlock ) => ( props ) => { diff --git a/packages/block-editor/src/hooks/layout.js b/packages/block-editor/src/hooks/layout.js index 2f56d3517cf5d..2ae0f9b319f79 100644 --- a/packages/block-editor/src/hooks/layout.js +++ b/packages/block-editor/src/hooks/layout.js @@ -144,8 +144,9 @@ function LayoutPanel( { setAttributes, attributes } ) { /** * Filters registered block settings, extending attributes to include `layout`. * - * @param {Object} settings Original block settings - * @return {Object} Filtered block settings + * @param {Object} settings Original block settings. + * + * @return {Object} Filtered block settings. */ export function addAttribute( settings ) { if ( has( settings.attributes, [ 'layout', 'type' ] ) ) { @@ -166,8 +167,9 @@ export function addAttribute( settings ) { /** * Override the default edit UI to include layout controls * - * @param {Function} BlockEdit Original component - * @return {Function} Wrapped component + * @param {Function} BlockEdit Original component. + * + * @return {Function} Wrapped component. */ export const withInspectorControls = createHigherOrderComponent( ( BlockEdit ) => ( props ) => { @@ -188,8 +190,9 @@ export const withInspectorControls = createHigherOrderComponent( /** * Override the default block element to add the layout styles. * - * @param {Function} BlockListBlock Original component - * @return {Function} Wrapped component + * @param {Function} BlockListBlock Original component. + * + * @return {Function} Wrapped component. */ export const withLayoutStyles = createHigherOrderComponent( ( BlockListBlock ) => ( props ) => { diff --git a/packages/block-editor/src/hooks/letter-spacing.js b/packages/block-editor/src/hooks/letter-spacing.js index 0a70474c47803..6de6193fe4d81 100644 --- a/packages/block-editor/src/hooks/letter-spacing.js +++ b/packages/block-editor/src/hooks/letter-spacing.js @@ -19,7 +19,7 @@ export const LETTER_SPACING_SUPPORT_KEY = '__experimentalLetterSpacing'; /** * Inspector control panel containing the letter-spacing options. * - * @param {Object} props Block properties. + * @param {Object} props Block properties. * @return {WPElement} Letter-spacing edit element. */ export function LetterSpacingEdit( props ) { @@ -57,7 +57,7 @@ export function LetterSpacingEdit( props ) { /** * Checks if letter-spacing settings have been disabled. * - * @param {string} name Name of the block. + * @param {string} name Name of the block. * @return {boolean} Whether or not the setting is disabled. */ export function useIsLetterSpacingDisabled( { name: blockName } = {} ) { diff --git a/packages/block-editor/src/hooks/margin.js b/packages/block-editor/src/hooks/margin.js index 19a6103b8cb3a..c0cb5c5d4ef5d 100644 --- a/packages/block-editor/src/hooks/margin.js +++ b/packages/block-editor/src/hooks/margin.js @@ -19,8 +19,9 @@ import { cleanEmptyObject } from './utils'; /** * Determines if there is margin support. * - * @param {string|Object} blockType Block name or Block Type object. - * @return {boolean} Whether there is support. + * @param {string|Object} blockType Block name or Block Type object. + * + * @return {boolean} Whether there is support. */ export function hasMarginSupport( blockType ) { const support = getBlockSupport( blockType, SPACING_SUPPORT_KEY ); @@ -30,8 +31,9 @@ export function hasMarginSupport( blockType ) { /** * Custom hook that checks if margin settings have been disabled. * - * @param {string} name The name of the block. - * @return {boolean} Whether margin setting is disabled. + * @param {string} name The name of the block. + * + * @return {boolean} Whether margin setting is disabled. */ export function useIsMarginDisabled( { name: blockName } = {} ) { const isDisabled = ! useSetting( 'spacing.customMargin' ); @@ -41,8 +43,9 @@ export function useIsMarginDisabled( { name: blockName } = {} ) { /** * Inspector control panel containing the margin related configuration * - * @param {Object} props Block props. - * @return {WPElement} Margin edit element. + * @param {Object} props Block props. + * + * @return {WPElement} Margin edit element. */ export function MarginEdit( props ) { const { diff --git a/packages/block-editor/src/hooks/padding.js b/packages/block-editor/src/hooks/padding.js index 709470bed5cc9..6a29ad7fd7f00 100644 --- a/packages/block-editor/src/hooks/padding.js +++ b/packages/block-editor/src/hooks/padding.js @@ -19,8 +19,9 @@ import { cleanEmptyObject } from './utils'; /** * Determines if there is padding support. * - * @param {string|Object} blockType Block name or Block Type object. - * @return {boolean} Whether there is support. + * @param {string|Object} blockType Block name or Block Type object. + * + * @return {boolean} Whether there is support. */ export function hasPaddingSupport( blockType ) { const support = getBlockSupport( blockType, SPACING_SUPPORT_KEY ); @@ -30,8 +31,9 @@ export function hasPaddingSupport( blockType ) { /** * Custom hook that checks if padding settings have been disabled. * - * @param {string} name The name of the block. - * @return {boolean} Whether padding setting is disabled. + * @param {string} name The name of the block. + * + * @return {boolean} Whether padding setting is disabled. */ export function useIsPaddingDisabled( { name: blockName } = {} ) { const isDisabled = ! useSetting( 'spacing.customPadding' ); diff --git a/packages/block-editor/src/hooks/spacing.js b/packages/block-editor/src/hooks/spacing.js index a911727dd82f8..f356a211248f7 100644 --- a/packages/block-editor/src/hooks/spacing.js +++ b/packages/block-editor/src/hooks/spacing.js @@ -22,8 +22,9 @@ export const SPACING_SUPPORT_KEY = 'spacing'; /** * Inspector controls for spacing support. * - * @param {Object} props Block props. - * @return {WPElement} Inspector controls for spacing support features. + * @param {Object} props Block props. + * + * @return {WPElement} Inspector controls for spacing support features. */ export function SpacingPanel( props ) { const isDisabled = useIsSpacingDisabled( props ); @@ -47,7 +48,8 @@ export function SpacingPanel( props ) { * Determine whether there is block support for padding or margins. * * @param {string} blockName Block name. - * @return {boolean} Whether there is support. + * + * @return {boolean} Whether there is support. */ export function hasSpacingSupport( blockName ) { if ( Platform.OS !== 'web' ) { @@ -60,8 +62,9 @@ export function hasSpacingSupport( blockName ) { /** * Determines whether spacing support has been disabled. * - * @param {Object} props Block properties. - * @return {boolean} If spacing support is completely disabled. + * @param {Object} props Block properties. + * + * @return {boolean} If spacing support is completely disabled. */ const useIsSpacingDisabled = ( props = {} ) => { const paddingDisabled = useIsPaddingDisabled( props ); @@ -77,9 +80,10 @@ const useIsSpacingDisabled = ( props = {} ) => { * Sides are opted into by default. It is only if a specific side is set to * false that it is omitted. * - * @param {string} blockName Block name. - * @param {string} feature The feature custom sides relate to e.g. padding or margins. - * @return {Object} Sides supporting custom margin. + * @param {string} blockName Block name. + * @param {string} feature The feature custom sides relate to e.g. padding or margins. + * + * @return {Object} Sides supporting custom margin. */ export function useCustomSides( blockName, feature ) { const support = getBlockSupport( blockName, SPACING_SUPPORT_KEY ); diff --git a/packages/block-editor/src/hooks/style.js b/packages/block-editor/src/hooks/style.js index 601ceb6791f7d..f177ed5da8c9b 100644 --- a/packages/block-editor/src/hooks/style.js +++ b/packages/block-editor/src/hooks/style.js @@ -67,8 +67,9 @@ function compileStyleValue( uncompiledValue ) { /** * Returns the inline styles to add depending on the style object * - * @param {Object} styles Styles configuration - * @return {Object} Flattened CSS variables declaration + * @param {Object} styles Styles configuration. + * + * @return {Object} Flattened CSS variables declaration. */ export function getInlineStyles( styles = {} ) { const output = {}; @@ -115,8 +116,9 @@ function compileElementsStyles( selector, elements = {} ) { /** * Filters registered block settings, extending attributes to include `style` attribute. * - * @param {Object} settings Original block settings - * @return {Object} Filtered block settings + * @param {Object} settings Original block settings. + * + * @return {Object} Filtered block settings. */ function addAttribute( settings ) { if ( ! hasStyleSupport( settings ) ) { @@ -151,10 +153,11 @@ const skipSerializationPaths = { /** * 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 - * @return {Object} Filtered props applied to save element + * @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 ) { if ( ! hasStyleSupport( blockType ) ) { @@ -181,8 +184,9 @@ export function addSaveProps( props, blockType, attributes ) { * Filters registered block settings to extend the block edit wrapper * to apply the desired styles and classnames properly. * - * @param {Object} settings Original block settings - * @return {Object} Filtered block settings + * @param {Object} settings Original block settings. + * + * @return {Object}.Filtered block settings. */ export function addEditProps( settings ) { if ( ! hasStyleSupport( settings ) ) { @@ -206,8 +210,9 @@ 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 - * @return {Function} Wrapped component + * @param {Function} BlockEdit Original component. + * + * @return {Function} Wrapped component. */ export const withBlockControls = createHigherOrderComponent( ( BlockEdit ) => ( props ) => { @@ -233,7 +238,7 @@ export const withBlockControls = createHigherOrderComponent( /** * Override the default block element to include duotone styles. * - * @param {Function} BlockListBlock Original component + * @param {Function} BlockListBlock Original component * @return {Function} Wrapped component */ const withElementsStyles = createHigherOrderComponent( diff --git a/packages/block-editor/src/hooks/text-decoration.js b/packages/block-editor/src/hooks/text-decoration.js index b75054be29c10..2dae0d781cfd1 100644 --- a/packages/block-editor/src/hooks/text-decoration.js +++ b/packages/block-editor/src/hooks/text-decoration.js @@ -20,8 +20,9 @@ export const TEXT_DECORATION_SUPPORT_KEY = /** * Inspector control panel containing the text decoration options. * - * @param {Object} props Block properties. - * @return {WPElement} Text decoration edit element. + * @param {Object} props Block properties. + * + * @return {WPElement} Text decoration edit element. */ export function TextDecorationEdit( props ) { const { @@ -57,8 +58,9 @@ export function TextDecorationEdit( props ) { /** * Checks if text-decoration settings have been disabled. * - * @param {string} name Name of the block. - * @return {boolean} Whether or not the setting is disabled. + * @param {string} name Name of the block. + * + * @return {boolean} Whether or not the setting is disabled. */ export function useIsTextDecorationDisabled( { name: blockName } = {} ) { const notSupported = ! hasBlockSupport( diff --git a/packages/block-editor/src/hooks/text-transform.js b/packages/block-editor/src/hooks/text-transform.js index cfc7b426d8113..2dc98b9fd46ae 100644 --- a/packages/block-editor/src/hooks/text-transform.js +++ b/packages/block-editor/src/hooks/text-transform.js @@ -20,8 +20,9 @@ export const TEXT_TRANSFORM_SUPPORT_KEY = /** * Inspector control panel containing the text transform options. * - * @param {Object} props Block properties. - * @return {WPElement} Text transform edit element. + * @param {Object} props Block properties. + * + * @return {WPElement} Text transform edit element. */ export function TextTransformEdit( props ) { const { @@ -57,8 +58,9 @@ export function TextTransformEdit( props ) { /** * Checks if text-transform settings have been disabled. * - * @param {string} name Name of the block. - * @return {boolean} Whether or not the setting is disabled. + * @param {string} name Name of the block. + * + * @return {boolean} Whether or not the setting is disabled. */ export function useIsTextTransformDisabled( { name: blockName } = {} ) { const notSupported = ! hasBlockSupport( diff --git a/packages/block-editor/src/hooks/use-border-props.js b/packages/block-editor/src/hooks/use-border-props.js index ac9f7678cd795..d62d68365fe1b 100644 --- a/packages/block-editor/src/hooks/use-border-props.js +++ b/packages/block-editor/src/hooks/use-border-props.js @@ -23,9 +23,9 @@ const EMPTY_ARRAY = []; * Provides the CSS class names and inline styles for a block's border support * attributes. * - * @param {Object} attributes Block attributes. - * @param {string} attributes.borderColor Selected named border color. - * @param {Object} attributes.style Block's styles attribute. + * @param {Object} attributes Block attributes. + * @param {string} attributes.borderColor Selected named border color. + * @param {Object} attributes.style Block's styles attribute. * * @return {Object} Border block support derived CSS classes & styles. */ @@ -51,8 +51,9 @@ export function getBorderClassesAndStyles( { borderColor, style } ) { * Inline styles are forced for named colors to ensure these selections are * reflected when themes do not load their color stylesheets in the editor. * - * @param {Object} attributes Block attributes. - * @return {Object} ClassName & style props from border block support. + * @param {Object} attributes Block attributes. + * + * @return {Object} ClassName & style props from border block support. */ export function useBorderProps( attributes ) { const colors = useSetting( 'color.palette' ) || EMPTY_ARRAY; diff --git a/packages/block-editor/src/hooks/use-color-props.js b/packages/block-editor/src/hooks/use-color-props.js index 768a166c37651..a7ba08121fd0a 100644 --- a/packages/block-editor/src/hooks/use-color-props.js +++ b/packages/block-editor/src/hooks/use-color-props.js @@ -30,8 +30,9 @@ const EMPTY_ARRAY = []; * Provides the CSS class names and inline styles for a block's color support * attributes. * - * @param {Object} attributes Block attributes. - * @return {Object} Color block support derived CSS classes & styles. + * @param {Object} attributes Block attributes. + * + * @return {Object} Color block support derived CSS classes & styles. */ export function getColorClassesAndStyles( attributes ) { const { backgroundColor, textColor, gradient, style } = attributes; @@ -76,8 +77,9 @@ export function getColorClassesAndStyles( attributes ) { * Inline styles are forced for named colors to ensure these selections are * reflected when themes do not load their color stylesheets in the editor. * - * @param {Object} attributes Block attributes. - * @return {Object} ClassName & style props from colors block support. + * @param {Object} attributes Block attributes. + * + * @return {Object} ClassName & style props from colors block support. */ export function useColorProps( attributes ) { const { backgroundColor, textColor, gradient } = attributes; diff --git a/packages/block-editor/src/store/actions.js b/packages/block-editor/src/store/actions.js index 69da6c75860ed..bf83406bd2a29 100644 --- a/packages/block-editor/src/store/actions.js +++ b/packages/block-editor/src/store/actions.js @@ -154,10 +154,10 @@ export function receiveBlocks( blocks ) { * Returns an action object used in signalling that the multiple blocks' * attributes with the specified client IDs have been updated. * - * @param {string|string[]} clientIds Block client IDs. - * @param {Object} attributes Block attributes to be merged. Should be keyed by clientIds if - * uniqueByBlock is true. - * @param {boolean} uniqueByBlock true if each block in clientIds array has a unique set of attributes + * @param {string|string[]} clientIds Block client IDs. + * @param {Object} attributes Block attributes to be merged. Should be keyed by clientIds if + * uniqueByBlock is true. + * @param {boolean} uniqueByBlock true if each block in clientIds array has a unique set of attributes * @return {Object} Action object. */ export function updateBlockAttributes( @@ -198,7 +198,7 @@ export function updateBlock( clientId, updates ) { * * @param {string} clientId Block client ID. * @param {0|-1|null} initialPosition Optional initial position. Pass as -1 to - * reflect reverse selection. + * reflect reverse selection. * * @return {Object} Action object. */ @@ -446,10 +446,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. */ @@ -509,10 +509,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. */ @@ -534,11 +534,11 @@ 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. - * @param {?Object} meta Optional Meta values to be passed to the action object. + * @param {?Object} meta Optional Meta values to be passed to the action object. * * @return {Object} Action object. */ @@ -623,9 +623,9 @@ export function* insertBlocks( * Returns an action object used in signalling that the insertion point should * be shown. * - * @param {?string} rootClientId Optional root client ID of block list on - * which 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 {?number} index Index at which block should be inserted. * @param {Object} __unstableOptions Wether or not to show an inserter button. * * @return {Object} Action object. @@ -658,7 +658,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. */ @@ -1212,7 +1212,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 ) { @@ -1334,7 +1334,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 ) { @@ -1363,7 +1363,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/array.js b/packages/block-editor/src/store/array.js index 3a2977eb152ae..894b942970d54 100644 --- a/packages/block-editor/src/store/array.js +++ b/packages/block-editor/src/store/array.js @@ -10,7 +10,7 @@ import { castArray } from 'lodash'; * @param {*} elements Elements to insert. * @param {number} index Insert Position. * - * @return {Array} Result. + * @return {Array} Result. */ export function insertAt( array, elements, index ) { return [ @@ -28,7 +28,7 @@ export function insertAt( array, elements, index ) { * @param {number} to Destination index. * @param {number} count Number of elements to move. * - * @return {Array} Result. + * @return {Array} Result. */ export function moveTo( array, from, to, count = 1 ) { const withoutMovedElements = [ ...array ]; diff --git a/packages/block-editor/src/store/defaults.js b/packages/block-editor/src/store/defaults.js index 6a0d03f168c2b..49035943cb4a5 100644 --- a/packages/block-editor/src/store/defaults.js +++ b/packages/block-editor/src/store/defaults.js @@ -11,23 +11,23 @@ export const PREFERENCES_DEFAULTS = { * The default editor settings * * @typedef {Object} SETTINGS_DEFAULT - * @property {boolean} alignWide Enable/Disable Wide/Full Alignments - * @property {boolean} supportsLayout Enable/disable layouts support in container blocks. - * @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} focusMode Whether the focus mode is enabled or not - * @property {Array} styles Editor Styles - * @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 {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 {boolean} supportsLayout Enable/disable layouts support in container blocks. + * @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} focusMode Whether the focus mode is enabled or not + * @property {Array} styles Editor Styles + * @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 {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 fbc39f3905251..db5477661d50c 100644 --- a/packages/block-editor/src/store/reducer.js +++ b/packages/block-editor/src/store/reducer.js @@ -79,7 +79,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. @@ -137,9 +137,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 - * nested block client IDs. - * @param {?string} rootClientId The root client ID to search. Defaults to ''. + * @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 {?Object} controlledInnerBlocks The InnerBlocks controller state. * * @return {Array} List of descendant client IDs. @@ -1131,7 +1131,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. */ @@ -1458,8 +1458,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. */ @@ -1568,7 +1568,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. */ @@ -1689,8 +1689,8 @@ export function highlightedBlock( state, action ) { /** * Reducer returning the block insertion event list 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/block-editor/src/store/selectors.js b/packages/block-editor/src/store/selectors.js index de8dd02b2c0e4..2ebbb5c2e8e13 100644 --- a/packages/block-editor/src/store/selectors.js +++ b/packages/block-editor/src/store/selectors.js @@ -303,8 +303,8 @@ export const __unstableGetClientIdsTree = 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. */ @@ -529,8 +529,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. @@ -1232,7 +1232,8 @@ export function isValidTemplate( state ) { * Returns the defined block template * * @param {boolean} state - * @return {?Array} Block Template + * + * @return {?Array} Block Template. */ export function getTemplate( state ) { return state.settings.template; @@ -1281,11 +1282,11 @@ const checkAllowList = ( list, item, defaultResult = null ) => { * This function is not exported and not memoized because using a memoized selector * inside another memoized selector is just a waste of time. * - * @param {Object} state Editor state. - * @param {string|Object} blockName The block type object, e.g., the response - * from the block directory; or a string name of - * an installed block type, e.g.' core/paragraph'. - * @param {?string} rootClientId Optional root client ID of block list. + * @param {Object} state Editor state. + * @param {string|Object} blockName The block type object, e.g., the response + * from the block directory; or a string name of + * an installed block type, e.g.' core/paragraph'. + * @param {?string} rootClientId Optional root client ID of block list. * * @return {boolean} Whether the given block type is allowed to be inserted. */ @@ -1405,8 +1406,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. @@ -1423,7 +1424,7 @@ const canIncludeBlockTypeInInserter = ( state, blockType, rootClientId ) => { * Return a function to be used to tranform a block variation to an inserter item * * @param {Object} state Global State - * @param {Object} item Denormalized inserter item + * @param {Object} item Denormalized inserter item * @return {Function} Function to transform a block variation to inserter item */ const getItemFromVariation = ( state, item ) => ( variation ) => { @@ -1456,7 +1457,7 @@ const getItemFromVariation = ( state, item ) => ( variation ) => { * 'frecency' is a heuristic (https://en.wikipedia.org/wiki/Frecency) * that combines block usage frequenty and recency. * - * @param {number} time When the last insert occurred as a UNIX epoch + * @param {number} time When the last insert occurred as a UNIX epoch * @param {number} count The number of inserts that have occurred. * * @return {number} The calculated frecency. @@ -1485,8 +1486,8 @@ const calculateFrecency = ( time, count ) => { * in a specific context. It's used for building items for Inserter and available * block Transfroms list. * - * @param {Object} state Editor state. - * @param {Object} options Options object for handling the building of a block type. + * @param {Object} state Editor state. + * @param {Object} options Options object for handling the building of a block type. * @param {string} options.buildScope The scope for which the item is going to be used. * @return {Function} Function returns an item to be shown in a specific context (Inserter|Transforms list). */ @@ -1541,8 +1542,8 @@ const buildBlockTypeItem = ( state, { buildScope = 'inserter' } ) => ( * * Items are returned ordered descendingly by their 'utility' and 'frecency'. * - * @param {Object} state Editor state. - * @param {?string} rootClientId Optional root client ID of block list. + * @param {Object} state Editor state. + * @param {?string} rootClientId Optional root client ID of block list. * * @return {WPEditorInserterItem[]} Items that appear in inserter. * @@ -1671,19 +1672,19 @@ export const getInserterItems = createSelector( * * Items are returned ordered descendingly by their 'frecency'. * - * @param {Object} state Editor state. - * @param {?string} rootClientId Optional root client ID of block list. + * @param {Object} state Editor state. + * @param {?string} rootClientId Optional root client ID of block list. * * @return {WPEditorTransformItem[]} Items that appear in inserter. * * @typedef {Object} WPEditorTransformItem - * @property {string} id Unique identifier for the item. - * @property {string} name The type of block to create. - * @property {string} title Title of the item, as it appears in the inserter. - * @property {string} icon Dashicon for the item, as it appears in the inserter. - * @property {boolean} isDisabled Whether or not the user should be prevented from inserting - * this item. - * @property {number} frecency Heuristic that combines frequency and recency. + * @property {string} id Unique identifier for the item. + * @property {string} name The type of block to create. + * @property {string} title Title of the item, as it appears in the inserter. + * @property {string} icon Dashicon for the item, as it appears in the inserter. + * @property {boolean} isDisabled Whether or not the user should be prevented from inserting + * this item. + * @property {number} frecency Heuristic that combines frequency and recency. */ export const getBlockTransformItems = createSelector( ( state, blocks, rootClientId = null ) => { @@ -1880,9 +1881,9 @@ export const __experimentalGetAllowedPatterns = createSelector( * suggesting appropriate patterns in a Placeholder state(during insertion) * or blocks transformations. * - * @param {Object} state Editor state. - * @param {string|string[]} blockNames Block's name or array of block names to find matching pattens. - * @param {?string} rootClientId Optional target root client ID. + * @param {Object} state Editor state. + * @param {string|string[]} blockNames Block's name or array of block names to find matching pattens. + * @param {?string} rootClientId Optional target root client ID. * * @return {Array} The list of matched block patterns based on declared `blockTypes` and block name. */ @@ -1921,9 +1922,9 @@ export const __experimentalGetPatternsByBlockTypes = createSelector( * block pattern's blocks and try to find matches from the selected blocks. * Now this happens in the consumer to avoid heavy operations in the selector. * - * @param {Object} state Editor state. - * @param {Object[]} blocks The selected blocks. - * @param {?string} rootClientId Optional root client ID of block list. + * @param {Object} state Editor state. + * @param {Object[]} blocks The selected blocks. + * @param {?string} rootClientId Optional root client ID of block list. * * @return {WPBlockPattern[]} Items that are eligible for a pattern transformation. */ @@ -2131,7 +2132,7 @@ function getReusableBlocks( state ) { * * @param {Object} state Editor state. * - * @return {boolean} Is navigation mode enabled. + * @return {boolean} Is navigation mode enabled. */ export function isNavigationMode( state ) { return state.isNavigationMode; @@ -2142,7 +2143,7 @@ export function isNavigationMode( state ) { * * @param {Object} state Editor state. * - * @return {string} Client Id of moving block. + * @return {string} Client Id of moving block. */ export function hasBlockMovingClientId( state ) { return state.hasBlockMovingClientId; @@ -2162,7 +2163,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. @@ -2174,7 +2175,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. @@ -2188,7 +2189,7 @@ export function areInnerBlocksControlled( state, clientId ) { * A block is 'active' if it (or a child) is the selected block. * Returns the first match moving up the DOM from the selected block. * - * @param {Object} state Global application state. + * @param {Object} state Global application state. * @param {string[]} validBlocksNames The names of block types to check for. * * @return {string} The matching block's clientId. @@ -2232,9 +2233,9 @@ export const __experimentalGetActiveBlockIdByBlockNames = createSelector( /** * Tells if the block with the passed clientId was just inserted. * - * @param {Object} state Global application state. - * @param {Object} clientId Client Id of the block. - * @param {?string} source Optional insertion source of the block. + * @param {Object} state Global application state. + * @param {Object} clientId Client Id of the block. + * @param {?string} source Optional insertion source of the block. * @return {boolean} True if the block matches the last block inserted from the specified source. */ export function wasBlockJustInserted( state, clientId, source ) { diff --git a/packages/block-editor/src/utils/block-variation-transforms.js b/packages/block-editor/src/utils/block-variation-transforms.js index db0901e628012..19f8e05c82205 100644 --- a/packages/block-editor/src/utils/block-variation-transforms.js +++ b/packages/block-editor/src/utils/block-variation-transforms.js @@ -13,8 +13,8 @@ import { isMatch } from 'lodash'; * This is a simple implementation for now as it takes into account only the attributes * of a block variation and not `InnerBlocks`. * - * @param {Object} blockAttributes - The block attributes to try to find a match. - * @param {WPBlockVariation[]} variations - A list of block variations to test for a match. + * @param {Object} blockAttributes - The block attributes to try to find a match. + * @param {WPBlockVariation[]} variations - A list of block variations to test for a match. * @return {?WPBlockVariation} - If a match is found returns it. If not or more than one matches are found returns `undefined`. */ export const __experimentalGetMatchingVariation = ( diff --git a/packages/block-editor/src/utils/theme.js b/packages/block-editor/src/utils/theme.js index beb8bd8629fe1..fc14cf2a4be6c 100644 --- a/packages/block-editor/src/utils/theme.js +++ b/packages/block-editor/src/utils/theme.js @@ -6,7 +6,7 @@ import { SETTINGS_DEFAULTS } from '../store/defaults'; /** * Given an array of theme colors checks colors for validity * - * @param {Array} colors The array of theme colors + * @param {Array} colors The array of theme colors * * @return {Array} The array of valid theme colors or the default colors */ @@ -28,7 +28,7 @@ export function validateThemeColors( colors ) { /** * Given an array of theme gradients checks gradients for validity * - * @param {Array} gradients The array of theme gradients + * @param {Array} gradients The array of theme gradients * * @return {Array} The array of valid theme gradients or the default gradients */ diff --git a/packages/block-editor/src/utils/transform-styles/index.js b/packages/block-editor/src/utils/transform-styles/index.js index 763554707bd2e..4d4a4d0336ec9 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..146b09bab59e4 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,10 +51,10 @@ 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 + * @return {string} the full path to the file */ function getResourcePath( str, baseURL ) { return new URL( str, baseURL ).toString(); @@ -63,8 +63,9 @@ function getResourcePath( str, baseURL ) { /** * Process the single `url()` pattern * - * @param {string} baseURL the base URL for relative URLs - * @return {Promise} the Promise + * @param {string} baseURL the base URL for relative URLs. + * + * @return {Promise} the Promise. */ function processURL( baseURL ) { return ( meta ) => ( { @@ -83,9 +84,9 @@ 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 + * @return {Array} the urls. */ function getURLs( value ) { const reg = /url\((\s*)(['"]?)(.+?)\2(\s*)\)/g; @@ -110,10 +111,10 @@ 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 + * @return {string} the new value. */ function replaceURLs( raw, URLs ) { URLs.forEach( ( item ) => { diff --git a/packages/block-library/src/code/utils.js b/packages/block-library/src/code/utils.js index dcc2d1943422f..5cf110230f11d 100644 --- a/packages/block-library/src/code/utils.js +++ b/packages/block-library/src/code/utils.js @@ -24,7 +24,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. [ => [) @@ -43,7 +43,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/columns/utils.js b/packages/block-library/src/columns/utils.js index c99b4e504b07f..e79e20f6a1910 100644 --- a/packages/block-library/src/columns/utils.js +++ b/packages/block-library/src/columns/utils.js @@ -131,8 +131,8 @@ export function getMappedColumnWidths( blocks, widths ) { /** * Returns an array with columns widths values, parsed or no depends on `withParsing` flag. * - * @param {WPBlock[]} blocks Block objects. - * @param {?boolean} withParsing Whether value has to be parsed. + * @param {WPBlock[]} blocks Block objects. + * @param {?boolean} withParsing Whether value has to be parsed. * * @return {Array} Column widths. */ @@ -148,8 +148,8 @@ export function getWidths( blocks, withParsing = true ) { /** * Returns a column width with unit. * - * @param {string} width Column width. - * @param {string} unit Column width unit. + * @param {string} width Column width. + * @param {string} unit Column width unit. * * @return {string} Column width with unit. */ diff --git a/packages/block-library/src/embed/util.js b/packages/block-library/src/embed/util.js index bc49207a829eb..49e98b015ba9e 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 56561ae4d4fa1..ae17a005cfa03 100644 --- a/packages/block-library/src/image/edit.js +++ b/packages/block-library/src/image/edit.js @@ -53,7 +53,7 @@ export const pickRelevantMediaFiles = ( image, size ) => { * 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/legacy-widget/edit/control.js b/packages/block-library/src/legacy-widget/edit/control.js index a6867771f7b29..3bac5b86bef46 100644 --- a/packages/block-library/src/legacy-widget/edit/control.js +++ b/packages/block-library/src/legacy-widget/edit/control.js @@ -23,10 +23,10 @@ export default class Control { * Creates and loads a new control. * * @access public - * @param {Object} params - * @param {string} params.id - * @param {string} params.idBase - * @param {Object} params.instance + * @param {Object} params + * @param {string} params.id + * @param {string} params.idBase + * @param {Object} params.instance * @param {Function} params.onChangeInstance * @param {Function} params.onChangeHasPreview * @param {Function} params.onError diff --git a/packages/block-library/src/navigation-link/edit.js b/packages/block-library/src/navigation-link/edit.js index 8f225c499da96..641d95ec5c2e0 100644 --- a/packages/block-library/src/navigation-link/edit.js +++ b/packages/block-library/src/navigation-link/edit.js @@ -142,14 +142,14 @@ function getSuggestionsQuery( type, kind ) { * * @typedef {Object} WPNavigationLinkBlockAttributes * - * @property {string} [label] Link text. - * @property {WPNavigationLinkKind} [kind] Kind is used to differentiate between term and post ids to check post draft status. - * @property {string} [type] The type such as post, page, tag, category and other custom types. - * @property {string} [rel] The relationship of the linked URL. - * @property {number} [id] A post or term id. - * @property {boolean} [opensInNewTab] Sets link target to _blank when true. - * @property {string} [url] Link href. - * @property {string} [title] Link title attribute. + * @property {string} [label] Link text. + * @property {WPNavigationLinkKind} [kind] Kind is used to differentiate between term and post ids to check post draft status. + * @property {string} [type] The type such as post, page, tag, category and other custom types. + * @property {string} [rel] The relationship of the linked URL. + * @property {number} [id] A post or term id. + * @property {boolean} [opensInNewTab] Sets link target to _blank when true. + * @property {string} [url] Link href. + * @property {string} [title] Link title attribute. */ /** diff --git a/packages/block-library/src/navigation/menu-items-to-blocks.js b/packages/block-library/src/navigation/menu-items-to-blocks.js index 21bfd97529925..024c267d67cef 100644 --- a/packages/block-library/src/navigation/menu-items-to-blocks.js +++ b/packages/block-library/src/navigation/menu-items-to-blocks.js @@ -93,16 +93,16 @@ function mapMenuItemsToBlocks( menuItems ) { * * @typedef WPNavMenuItem * - * @property {Object} title stores the raw and rendered versions of the title/label for this menu item. - * @property {Array} xfn the XFN relationships expressed in the link of this menu item. - * @property {Array} classes the HTML class attributes for this menu item. - * @property {string} attr_title the HTML title attribute for this menu item. - * @property {string} object The type of object originally represented, such as 'category', 'post', or 'attachment'. - * @property {string} object_id The DB ID of the original object this menu item represents, e.g. ID for posts and term_id for categories. + * @property {Object} title stores the raw and rendered versions of the title/label for this menu item. + * @property {Array} xfn the XFN relationships expressed in the link of this menu item. + * @property {Array} classes the HTML class attributes for this menu item. + * @property {string} attr_title the HTML title attribute for this menu item. + * @property {string} object The type of object originally represented, such as 'category', 'post', or 'attachment'. + * @property {string} object_id The DB ID of the original object this menu item represents, e.g. ID for posts and term_id for categories. * @property {string} description The description of this menu item. - * @property {string} url The URL to which this menu item points. - * @property {string} type The family of objects originally represented, such as 'post_type' or 'taxonomy'. - * @property {string} target The target attribute of the link element for this menu item. + * @property {string} url The URL to which this menu item points. + * @property {string} type The family of objects originally represented, such as 'post_type' or 'taxonomy'. + * @property {string} target The target attribute of the link element for this menu item. */ /** @@ -175,9 +175,9 @@ function menuItemToBlockAttributes( { * * 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/navigation/use-navigation-entities.js b/packages/block-library/src/navigation/use-navigation-entities.js index 03dceb167e9a9..17806deadd9a8 100644 --- a/packages/block-library/src/navigation/use-navigation-entities.js +++ b/packages/block-library/src/navigation/use-navigation-entities.js @@ -6,16 +6,16 @@ import { store as coreStore } from '@wordpress/core-data'; /** * @typedef {Object} NavigationEntitiesData - * @property {Array|undefined} pages - a collection of WP Post entity objects of post type "Page". - * @property {boolean} isResolvingPages - indicates whether the request to fetch pages is currently resolving. - * @property {boolean} hasResolvedPages - indicates whether the request to fetch pages has finished resolving. - * @property {Array|undefined} menus - a collection of Menu entity objects. - * @property {boolean} isResolvingMenus - indicates whether the request to fetch menus is currently resolving. - * @property {boolean} hasResolvedMenus - indicates whether the request to fetch menus has finished resolving. - * @property {Array|undefined} menusItems - a collection of Menu Item entity objects for the current menuId. - * @property {boolean} hasResolvedMenuItems - indicates whether the request to fetch menuItems has finished resolving. - * @property {boolean} hasPages - indicates whether there is currently any data for pages. - * @property {boolean} hasMenus - indicates whether there is currently any data for menus. + * @property {Array|undefined} pages - a collection of WP Post entity objects of post type "Page". + * @property {boolean} isResolvingPages - indicates whether the request to fetch pages is currently resolving. + * @property {boolean} hasResolvedPages - indicates whether the request to fetch pages has finished resolving. + * @property {Array|undefined} menus - a collection of Menu entity objects. + * @property {boolean} isResolvingMenus - indicates whether the request to fetch menus is currently resolving. + * @property {boolean} hasResolvedMenus - indicates whether the request to fetch menus has finished resolving. + * @property {Array|undefined} menusItems - a collection of Menu Item entity objects for the current menuId. + * @property {boolean} hasResolvedMenuItems - indicates whether the request to fetch menuItems has finished resolving. + * @property {boolean} hasPages - indicates whether there is currently any data for pages. + * @property {boolean} hasMenus - indicates whether there is currently any data for menus. */ /** diff --git a/packages/block-library/src/query/hooks.js b/packages/block-library/src/query/hooks.js index 841cf185f422e..b2bb32a7be7b4 100644 --- a/packages/block-library/src/query/hooks.js +++ b/packages/block-library/src/query/hooks.js @@ -28,7 +28,7 @@ const CreateNewPostLink = ( { /** * Override the default edit UI to include layout controls * - * @param {Function} BlockEdit Original component + * @param {Function} BlockEdit Original component * @return {Function} Wrapped component */ const queryTopInspectorControls = createHigherOrderComponent( diff --git a/packages/block-library/src/query/utils.js b/packages/block-library/src/query/utils.js index d77961346ad15..16231222c4e62 100644 --- a/packages/block-library/src/query/utils.js +++ b/packages/block-library/src/query/utils.js @@ -11,15 +11,15 @@ import { store as coreStore } from '@wordpress/core-data'; * 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. */ /** @@ -27,10 +27,10 @@ import { store as coreStore } from '@wordpress/core-data'; * from an array of WPTerm. * * @typedef {Object} QueryTermsInfo - * @property {WPTerm[]} terms The array of terms. - * @property {Object} mapById Object mapping with the term id as key and the term as value. + * @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-of-contents/edit.js b/packages/block-library/src/table-of-contents/edit.js index 095a35800da8b..5a8ff05fe23b9 100644 --- a/packages/block-library/src/table-of-contents/edit.js +++ b/packages/block-library/src/table-of-contents/edit.js @@ -35,11 +35,11 @@ import { getHeadingsFromContent, linearToNestedHeadingList } from './utils'; /** * Table of Contents block edit component. * - * @param {Object} props The props. - * @param {Object} props.attributes The block attributes. + * @param {Object} props The props. + * @param {Object} props.attributes The block attributes. * @param {boolean} props.attributes.onlyIncludeCurrentPage - * Whether to only include headings from the current page (if the post is - * paginated). + * Whether to only include headings from the current page (if the post is + * paginated). * @param {string} props.clientId * @param {(attributes: Object) => void} props.setAttributes * 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/block-library/src/template-part/edit/utils/create-template-part-id.js b/packages/block-library/src/template-part/edit/utils/create-template-part-id.js index 1612fa32f9c40..5bf05fd16d311 100644 --- a/packages/block-library/src/template-part/edit/utils/create-template-part-id.js +++ b/packages/block-library/src/template-part/edit/utils/create-template-part-id.js @@ -2,7 +2,7 @@ * Generates a template part Id based on slug and theme inputs. * * @param {string} theme the template part's theme. - * @param {string} slug the template part's slug + * @param {string} slug the template part's slug * @return {string|null} the template part's Id. */ export function createTemplatePartId( theme, slug ) { diff --git a/packages/blocks/README.md b/packages/blocks/README.md index dd51909dedfd4..4b7109bd1fe31 100644 --- a/packages/blocks/README.md +++ b/packages/blocks/README.md @@ -238,7 +238,7 @@ _Parameters_ _Returns_ -- `boolean`: Whether the list of blocks matches a templates +- `boolean`: Whether the list of blocks matches a templates. # **findTransform** diff --git a/packages/blocks/src/api/factory.js b/packages/blocks/src/api/factory.js index a0fab5c32cd39..5b1239c46fc7c 100644 --- a/packages/blocks/src/api/factory.js +++ b/packages/blocks/src/api/factory.js @@ -97,9 +97,9 @@ export function createBlocksFromInnerBlocksTemplate( * Given a block object, returns a copy of the block object while sanitizing its attributes, * 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. */ @@ -134,9 +134,9 @@ export function __experimentalCloneSanitizedBlock( * 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. */ @@ -162,7 +162,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? */ @@ -244,7 +244,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. */ @@ -327,7 +327,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 */ @@ -399,8 +399,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 c2c34f341d3fd..891034d3c3c27 100644 --- a/packages/blocks/src/api/node.js +++ b/packages/blocks/src/api/node.js @@ -19,7 +19,7 @@ import * as children from './children'; * 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 edffe4b4af462..500823eea074e 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. */ @@ -409,7 +409,7 @@ export function getMigratedBlock( block, parsedAttributes ) { * both in the parser level for previous content and to convert such blocks * used in Custom Post Types templates. * - * @param {string} name The block's name + * @param {string} name The block's name * @param {Object} attributes The block's attributes * * @return {Object} The block's name and attributes, changed accordingly if a match was found diff --git a/packages/blocks/src/api/raw-handling/paste-handler.js b/packages/blocks/src/api/raw-handling/paste-handler.js index 575aaf6864257..a63613bdab4bc 100644 --- a/packages/blocks/src/api/raw-handling/paste-handler.js +++ b/packages/blocks/src/api/raw-handling/paste-handler.js @@ -43,7 +43,7 @@ const { console } = window; /** * Filters HTML to only contain phrasing content. * - * @param {string} HTML The HTML to filter. + * @param {string} HTML The HTML to filter. * @param {boolean} preserveWhiteSpace Whether or not to preserve consequent white space. * * @return {string} HTML only containing phrasing content. @@ -72,13 +72,13 @@ function filterInlineHTML( HTML, preserveWhiteSpace ) { * 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. - * * '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 {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 {boolean} [options.preserveWhiteSpace] Whether or not to preserve consequent white space. * * @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 bd55ab95d60f4..924267b9ad07c 100644 --- a/packages/blocks/src/api/registration.js +++ b/packages/blocks/src/api/registration.js @@ -87,37 +87,37 @@ import { store as blocksStore } from '../store'; * * @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 {string} [category] Block type category classification, - * used in search interfaces to arrange - * block types by category. - * @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 - * 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 - * is applicable. When not provided, it - * assumes all available scopes. - * @property {string[]} [keywords] An array of terms (which can be translated) - * that help users discover the variation - * while searching. - * @property {Function|string[]} [isActive] This can be a function or an array of block attributes. - * Function that accepts a block's attributes and the - * variation's attributes and determines if a variation is active. - * This function doesn't try to find a match dynamically based - * on all block's attributes, as in many cases some attributes are irrelevant. - * An example would be for `embed` block where we only care - * about `providerNameSlug` attribute's value. - * We can also use a `string[]` to tell which attributes - * should be compared as a shorthand. Each attributes will - * be matched and the variation will be active if all of them are matching. + * @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 {string} [category] Block type category classification, + * used in search interfaces to arrange + * block types by category. + * @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 + * 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 + * is applicable. When not provided, it + * assumes all available scopes. + * @property {string[]} [keywords] An array of terms (which can be translated) + * that help users discover the variation + * while searching. + * @property {Function|string[]} [isActive] This can be a function or an array of block attributes. + * Function that accepts a block's attributes and the + * variation's attributes and determines if a variation is active. + * This function doesn't try to find a match dynamically based + * on all block's attributes, as in many cases some attributes are irrelevant. + * An example would be for `embed` block where we only care + * about `providerNameSlug` attribute's value. + * We can also use a `string[]` to tell which attributes + * should be compared as a shorthand. Each attributes will + * be matched and the variation will be active if all of them are matching. */ /** @@ -375,9 +375,9 @@ export function registerBlockType( blockNameOrMetadata, settings ) { /** * Translates block settings provided with metadata using the i18n schema. * - * @param {string|string[]|Object[]} i18nSchema I18n schema for the block setting. - * @param {string|string[]|Object[]} settingValue Value for the block setting. - * @param {string} textdomain Textdomain to use with translations. + * @param {string|string[]|Object[]} i18nSchema I18n schema for the block setting. + * @param {string|string[]|Object[]} settingValue Value for the block setting. + * @param {string} textdomain Textdomain to use with translations. * * @return {string|string[]|Object[]} Translated setting. */ @@ -429,8 +429,8 @@ function translateBlockSettingUsingI18nSchema( * * @deprecated Use `registerBlockType` instead. * - * @param {Object} metadata Block metadata loaded from `block.json`. - * @param {Object} additionalSettings Additional block settings. + * @param {Object} metadata Block metadata loaded from `block.json`. + * @param {Object} additionalSettings Additional block settings. * * @return {?WPBlock} The block, if it has been successfully registered; * otherwise `undefined`. @@ -582,10 +582,10 @@ 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 - * explicitly defined + * @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 fe68c9eae1169..c88828b9cda79 100644 --- a/packages/blocks/src/api/serializer.js +++ b/packages/blocks/src/api/serializer.js @@ -91,9 +91,9 @@ export function getBlockProps( props = {} ) { * 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. */ @@ -196,7 +196,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 a0cfc9dc34d8a..8e5593c84a40e 100644 --- a/packages/blocks/src/api/templates.js +++ b/packages/blocks/src/api/templates.js @@ -18,10 +18,10 @@ 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 + * @return {boolean} Whether the list of blocks matches a templates. */ export function doBlocksMatchTemplate( blocks = [], template = [] ) { return ( @@ -44,10 +44,10 @@ 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. + * @return {Array} Updated Block list. */ export function synchronizeBlocksWithTemplate( blocks = [], template ) { // If no template is provided, return blocks unmodified. diff --git a/packages/blocks/src/api/utils.js b/packages/blocks/src/api/utils.js index c14f5d003dd25..d6b588668b0ed 100644 --- a/packages/blocks/src/api/utils.js +++ b/packages/blocks/src/api/utils.js @@ -30,9 +30,9 @@ 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 + * @return {boolean} Whether the block is an unmodified default block */ export function isUnmodifiedDefaultBlock( block ) { const defaultBlockName = getDefaultBlockName(); @@ -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 56492fb5e7c39..025912afdbc90 100644 --- a/packages/blocks/src/api/validation/index.js +++ b/packages/blocks/src/api/validation/index.js @@ -556,8 +556,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 */ @@ -677,7 +677,7 @@ export function isEquivalentHTML( actual, expected, logger = createLogger() ) { * @param {string|Object} blockTypeOrName Block type. * @param {Object} attributes Parsed block attributes. * @param {string} originalBlockContent Original block content. - * @param {Object} logger Validation logger object. + * @param {Object} logger Validation logger object. * * @return {Object} Whether block is valid and contains validation messages. */ 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 f0cb1632805fe..6eb859369b320 100644 --- a/packages/blocks/src/store/reducer.js +++ b/packages/blocks/src/store/reducer.js @@ -172,7 +172,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 3c8f4972f30ea..80607574dea91 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. */ @@ -253,11 +253,11 @@ 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 {Array|string} feature Feature to retrieve - * @param {*} defaultSupports Default value to return if not - * explicitly defined + * @param {Object} state Data state. + * @param {(string|Object)} nameOrType Block name or type object + * @param {Array|string} feature Feature to retrieve + * @param {*} defaultSupports Default value to return if not + * explicitly defined * * @return {?*} Block support value */ @@ -278,7 +278,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 f801d4be21e25..31082b393d24d 100644 --- a/packages/components/src/autocomplete/index.js +++ b/packages/components/src/autocomplete/index.js @@ -86,7 +86,7 @@ import { getAutoCompleterUI } from './autocompleter-ui'; /** * @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. */ /** @@ -98,7 +98,7 @@ import { getAutoCompleterUI } from './autocompleter-ui'; /** * @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 @@ -107,15 +107,15 @@ import { getAutoCompleterUI } from './autocompleter-ui'; /** * @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 useAutocomplete( { diff --git a/packages/components/src/base-control/index.js b/packages/components/src/base-control/index.js index 912a547591a40..aaae49a9a95da 100644 --- a/packages/components/src/base-control/index.js +++ b/packages/components/src/base-control/index.js @@ -16,18 +16,18 @@ import { /** * @typedef Props - * @property {string} id The id of the element to which labels and help text are being generated. - * That element should be passed as a child. - * @property {import('react').ReactNode} help If this property is added, a help text will be - * generated using help property as the content. - * @property {import('react').ReactNode} label If this property is added, a label will be generated - * using label property as the content. - * @property {boolean} [hideLabelFromVision] If true, the label will only be visible to screen readers. - * @property {string} [className] The class that will be added with "components-base-control" to the - * classes of the wrapper div. If no className is passed only - * components-base-control is used. - * @property {import('react').ReactNode} [children] The content to be displayed within - * the BaseControl. + * @property {string} id The id of the element to which labels and help text are being generated. + * That element should be passed as a child. + * @property {import('react').ReactNode} help If this property is added, a help text will be + * generated using help property as the content. + * @property {import('react').ReactNode} label If this property is added, a label will be generated + * using label property as the content. + * @property {boolean} [hideLabelFromVision] If true, the label will only be visible to screen readers. + * @property {string} [className] The class that will be added with "components-base-control" to the + * classes of the wrapper div. If no className is passed only + * components-base-control is used. + * @property {import('react').ReactNode} [children] The content to be displayed within + * the BaseControl. */ /** @@ -86,8 +86,8 @@ function BaseControl( { /** * @typedef VisualLabelProps - * @property {string} [className] Class name - * @property {import('react').ReactNode} [children] Children + * @property {string} [className] Class name + * @property {import('react').ReactNode} [children] Children */ /** diff --git a/packages/components/src/base-field/hook.js b/packages/components/src/base-field/hook.js index 479b545509e7e..7fbcf01394633 100644 --- a/packages/components/src/base-field/hook.js +++ b/packages/components/src/base-field/hook.js @@ -19,7 +19,7 @@ import * as styles from './styles'; /** * @typedef OwnProps * @property {boolean} [hasError=false] Renders an error. - * @property {boolean} [disabled] Whether the field is disabled. + * @property {boolean} [disabled] Whether the field is disabled. * @property {boolean} [isInline=false] Renders as an inline element (layout). * @property {boolean} [isSubtle=false] Renders a subtle variant. */ diff --git a/packages/components/src/color-picker/index.js b/packages/components/src/color-picker/index.js index c2f1e4850e917..010713aa35f41 100644 --- a/packages/components/src/color-picker/index.js +++ b/packages/components/src/color-picker/index.js @@ -90,27 +90,27 @@ 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: - * - when source = `rgb`, valuKey can be `r`, `g`, `b`, or `a`. - * - when source = `hsl`, valuKey can be `h`, `s`, `l`, or `a`. + * @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: * { source: 'rgb', r: 1, g: 2, b:3, a:0 } */ 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/dashicon/index.js b/packages/components/src/dashicon/index.js index 97f90b70bf4fd..c57ec0255bf62 100644 --- a/packages/components/src/dashicon/index.js +++ b/packages/components/src/dashicon/index.js @@ -1,8 +1,8 @@ /** * @typedef OwnProps * - * @property {import('./types').IconKey} icon Icon name - * @property {string} [className] Class name + * @property {import('./types').IconKey} icon Icon name + * @property {string} [className] Class name */ /** @typedef {import('react').ComponentPropsWithoutRef<'span'> & OwnProps} Props */ diff --git a/packages/components/src/dimension-control/sizes.js b/packages/components/src/dimension-control/sizes.js index f1d768894dda2..4a77ef25ff773 100644 --- a/packages/components/src/dimension-control/sizes.js +++ b/packages/components/src/dimension-control/sizes.js @@ -16,9 +16,10 @@ 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`) - * @return {Object} the matching size definition + * @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 ) => sizes.find( ( size ) => slug === size.slug ); diff --git a/packages/components/src/disabled/index.js b/packages/components/src/disabled/index.js index dbe80042c35b5..156a28eaafdea 100644 --- a/packages/components/src/disabled/index.js +++ b/packages/components/src/disabled/index.js @@ -44,9 +44,9 @@ const DISABLED_ELIGIBLE_NODE_NAMES = [ /** * @typedef OwnProps - * @property {string} [className] Classname for the disabled element. - * @property {import('react').ReactNode} children Children to disable. - * @property {boolean} [isDisabled=true] Whether to disable the children. + * @property {string} [className] Classname for the disabled element. + * @property {import('react').ReactNode} children Children to disable. + * @property {boolean} [isDisabled=true] Whether to disable the children. */ /** diff --git a/packages/components/src/draggable/index.js b/packages/components/src/draggable/index.js index e4a9b43059da8..9d9bd0d816466 100644 --- a/packages/components/src/draggable/index.js +++ b/packages/components/src/draggable/index.js @@ -12,20 +12,20 @@ const bodyClass = 'is-dragging-components-draggable'; /** * @typedef RenderProp * @property {(event: import('react').DragEvent) => void} onDraggableStart `onDragStart` handler. - * @property {(event: import('react').DragEvent) => void} onDraggableEnd `onDragEnd` handler. + * @property {(event: import('react').DragEvent) => void} onDraggableEnd `onDragEnd` handler. */ /** * @typedef Props - * @property {(props: RenderProp) => JSX.Element | null} children Children. - * @property {(event: import('react').DragEvent) => void} [onDragStart] Callback when dragging starts. - * @property {(event: import('react').DragEvent) => void} [onDragOver] Callback when dragging happens over the document. - * @property {(event: import('react').DragEvent) => void} [onDragEnd] Callback when dragging ends. - * @property {string} [cloneClassname] Classname for the cloned element. - * @property {string} [elementId] ID for the element. - * @property {any} [transferData] Transfer data for the drag event. - * @property {string} [__experimentalTransferDataType] The transfer data type to set. - * @property {import('react').ReactNode} __experimentalDragComponent Component to show when dragging. + * @property {(props: RenderProp) => JSX.Element | null} children Children. + * @property {(event: import('react').DragEvent) => void} [onDragStart] Callback when dragging starts. + * @property {(event: import('react').DragEvent) => void} [onDragOver] Callback when dragging happens over the document. + * @property {(event: import('react').DragEvent) => void} [onDragEnd] Callback when dragging ends. + * @property {string} [cloneClassname] Classname for the cloned element. + * @property {string} [elementId] ID for the element. + * @property {any} [transferData] Transfer data for the drag event. + * @property {string} [__experimentalTransferDataType] The transfer data type to set. + * @property {import('react').ReactNode} __experimentalDragComponent Component to show when dragging. */ /** diff --git a/packages/components/src/flex/flex/component.js b/packages/components/src/flex/flex/component.js index f2241aa47511e..70c4e448985e0 100644 --- a/packages/components/src/flex/flex/component.js +++ b/packages/components/src/flex/flex/component.js @@ -8,7 +8,7 @@ import { View } from '../../view'; /** * @param {import('../../ui/context').PolymorphicComponentProps} props - * @param {import('react').Ref} forwardedRef + * @param {import('react').Ref} forwardedRef */ function Flex( props, forwardedRef ) { const { children, isColumn, ...otherProps } = useFlex( props ); diff --git a/packages/components/src/h-stack/utils.js b/packages/components/src/h-stack/utils.js index 288cdc79b7db9..d5bd304ca7893 100644 --- a/packages/components/src/h-stack/utils.js +++ b/packages/components/src/h-stack/utils.js @@ -35,8 +35,8 @@ const V_ALIGNMENTS = { /* eslint-disable jsdoc/valid-types */ /** - * @param {import('./types').HStackAlignment | import('react').CSSProperties[ 'alignItems' ]} alignment Where to align. - * @param {import('../flex/types').FlexDirection} [direction='row'] Direction to align. + * @param {import('./types').HStackAlignment | import('react').CSSProperties[ 'alignItems' ]} alignment Where to align. + * @param {import('../flex/types').FlexDirection} [direction='row'] Direction to align. * @return {import('./types').AlignmentProps} Alignment props. */ /* eslint-enable jsdoc/valid-types */ diff --git a/packages/components/src/higher-order/with-focus-return/index.js b/packages/components/src/higher-order/with-focus-return/index.js index 8f585c9b4d717..858584a6296ab 100644 --- a/packages/components/src/higher-order/with-focus-return/index.js +++ b/packages/components/src/higher-order/with-focus-return/index.js @@ -24,9 +24,9 @@ function isComponentLike( object ) { * when the component is unmounted. * * @param {(WPComponent|Object)} options The component to be enhanced with - * focus return behavior, or an object - * describing the component and the - * focus return characteristics. + * focus return behavior, or an object + * describing the component and the + * focus return characteristics. * * @return {Function} Higher Order Component with the focus restauration behaviour. */ diff --git a/packages/components/src/higher-order/with-notices/index.js b/packages/components/src/higher-order/with-notices/index.js index eaa6d4c74c0d0..d6b50937a53a3 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. */ @@ -29,7 +29,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. */ const createNotice = ( notice ) => { const noticeToAdd = notice.id @@ -44,7 +44,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 ) => { createNotice( { @@ -56,7 +56,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 ) => { setNoticeList( ( current ) => diff --git a/packages/components/src/input-control/state.js b/packages/components/src/input-control/state.js index df4355528e7d5..d0e0a413ed578 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 ) => { @@ -167,7 +167,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 bc40ef2f13f95..ae896c4932e55 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..98422a9c6316b 100644 --- a/packages/components/src/notice/list.js +++ b/packages/components/src/notice/list.js @@ -12,12 +12,13 @@ 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. - * @return {Object} The rendered notices 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 } ) { const removeNotice = ( id ) => () => onRemove( id ); diff --git a/packages/components/src/number-control/index.js b/packages/components/src/number-control/index.js index cbcca8ed0e20f..519cbbb57f064 100644 --- a/packages/components/src/number-control/index.js +++ b/packages/components/src/number-control/index.js @@ -56,7 +56,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/placeholder/index.js b/packages/components/src/placeholder/index.js index ecc37801e906f..2dbed625f1809 100644 --- a/packages/components/src/placeholder/index.js +++ b/packages/components/src/placeholder/index.js @@ -26,7 +26,7 @@ import Icon from '../icon'; * @param {Object} props.preview Preview to be rendered in the placeholder. * @param {boolean} props.isColumnLayout Whether a column layout should be used. * - * @return {Object} The rendered placeholder. + * @return {Object} The rendered placeholder. */ function Placeholder( { icon, diff --git a/packages/components/src/popover/utils.js b/packages/components/src/popover/utils.js index f7021198085a2..25af0b8245507 100644 --- a/packages/components/src/popover/utils.js +++ b/packages/components/src/popover/utils.js @@ -287,7 +287,7 @@ export function computePopoverYAxisPosition( * relative positioned parent container. * @param {Element} boundaryElement Boundary element. * @param {boolean} forcePosition Don't adjust position based on anchor. - * @param {boolean} forceXAlignment Don't adjust alignment based on YAxis + * @param {boolean} forceXAlignment Don't adjust alignment based on YAxis * * @return {Object} Popover position and constraints. */ 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/range-control/utils.js b/packages/components/src/range-control/utils.js index 5422bce3a6285..81e03015e44c4 100644 --- a/packages/components/src/range-control/utils.js +++ b/packages/components/src/range-control/utils.js @@ -36,7 +36,7 @@ export function floatClamp( value, min, max ) { * @param {Object} settings Hook settings. * @param {number} settings.min The minimum value. * @param {number} settings.max The maximum value. - * @param {number} settings.value The current value. + * @param {number} settings.value The current value. * @param {any} settings.initial The initial value. * * @return {[*, Function]} The controlled value and the value setter. diff --git a/packages/components/src/resizable-box/resize-tooltip/utils.js b/packages/components/src/resizable-box/resize-tooltip/utils.js index cbd304ac4e0fb..beb31ecc85655 100644 --- a/packages/components/src/resizable-box/resize-tooltip/utils.js +++ b/packages/components/src/resizable-box/resize-tooltip/utils.js @@ -20,20 +20,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/scrollable/component.js b/packages/components/src/scrollable/component.js index 7b3bee6482769..d89d42d85f5dd 100644 --- a/packages/components/src/scrollable/component.js +++ b/packages/components/src/scrollable/component.js @@ -10,7 +10,7 @@ import { useScrollable } from './hook'; * @example * ```jsx * import { __experimentalScrollable as Scrollable } from `@wordpress/components/ui`; - + * * function Example() { * return ( * diff --git a/packages/components/src/shortcut/index.js b/packages/components/src/shortcut/index.js index 5528f193ae11a..7863fa1d574b8 100644 --- a/packages/components/src/shortcut/index.js +++ b/packages/components/src/shortcut/index.js @@ -6,8 +6,8 @@ import { isString, isObject } from 'lodash'; /** @typedef {string | { display: string, ariaLabel: string }} Shortcut */ /** * @typedef Props - * @property {Shortcut} shortcut Shortcut configuration - * @property {string} [className] Classname + * @property {Shortcut} shortcut Shortcut configuration + * @property {string} [className] Classname */ /** diff --git a/packages/components/src/snackbar/list.js b/packages/components/src/snackbar/list.js index 1246822590fcc..cc0c8dc7e0cd9 100644 --- a/packages/components/src/snackbar/list.js +++ b/packages/components/src/snackbar/list.js @@ -19,12 +19,13 @@ 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. - * @return {Object} The rendered notices 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 } ) { const isReducedMotion = useReducedMotion(); diff --git a/packages/components/src/surface/styles.js b/packages/components/src/surface/styles.js index 133bc8451e959..e758fc84ea177 100644 --- a/packages/components/src/surface/styles.js +++ b/packages/components/src/surface/styles.js @@ -19,7 +19,7 @@ export const background = css` `; /** - * @param {Object} props + * @param {Object} props * @param {boolean} [props.borderBottom] * @param {boolean} [props.borderLeft] * @param {boolean} [props.borderRight] @@ -137,8 +137,8 @@ export const getGrid = ( surfaceBackgroundSize ) => { /** * @param {'dotted' | 'grid' | 'primary' | 'secondary' | 'tertiary'} variant - * @param {string} surfaceBackgroundSize - * @param {string} surfaceBackgroundSizeDotted + * @param {string} surfaceBackgroundSize + * @param {string} surfaceBackgroundSizeDotted */ export const getVariant = ( variant, diff --git a/packages/components/src/text-control/index.js b/packages/components/src/text-control/index.js index ba1654ddd511e..394da3644ce49 100644 --- a/packages/components/src/text-control/index.js +++ b/packages/components/src/text-control/index.js @@ -11,20 +11,20 @@ import BaseControl from '../base-control'; /** * @typedef OwnProps - * @property {string} label Label for the control. - * @property {boolean} [hideLabelFromVision] Whether to accessibly hide the label. - * @property {string} value Value of the input. - * @property {string} [help] Optional help text for the control. - * @property {string} [className] Classname passed to BaseControl wrapper - * @property {(value: string) => void} onChange Handle changes. - * @property {string} [type='text'] Type of the input. + * @property {string} label Label for the control. + * @property {boolean} [hideLabelFromVision] Whether to accessibly hide the label. + * @property {string} value Value of the input. + * @property {string} [help] Optional help text for the control. + * @property {string} [className] Classname passed to BaseControl wrapper + * @property {(value: string) => void} onChange Handle changes. + * @property {string} [type='text'] Type of the input. */ /** @typedef {OwnProps & import('react').ComponentProps<'input'>} Props */ /** * - * @param {Props} props Props + * @param {Props} props Props * @param {import('react').Ref} [ref] */ function TextControl( diff --git a/packages/components/src/text/utils.js b/packages/components/src/text/utils.js index 4d674cd6871dc..4e5208c580f84 100644 --- a/packages/components/src/text/utils.js +++ b/packages/components/src/text/utils.js @@ -17,20 +17,20 @@ import { createElement } from '@wordpress/element'; /* eslint-disable jsdoc/valid-types */ /** * @typedef Options - * @property {string} [activeClassName=''] Classname for active highlighted areas. - * @property {number} [activeIndex=-1] The index of the active highlighted area. - * @property {import('react').AllHTMLAttributes['style']} [activeStyle] Styles to apply to the active highlighted area. - * @property {boolean} [autoEscape] Whether to automatically escape text. - * @property {boolean} [caseSensitive=false] Whether to highlight in a case-sensitive manner. - * @property {string} children Children to highlight. - * @property {import('highlight-words-core').FindAllArgs['findChunks']} [findChunks] Custom `findChunks` function to pass to `highlight-words-core`. - * @property {string | Record} [highlightClassName=''] Classname to apply to highlighted text or a Record of classnames to apply to given text (which should be the key). - * @property {import('react').AllHTMLAttributes['style']} [highlightStyle={}] Styles to apply to highlighted text. - * @property {keyof JSX.IntrinsicElements} [highlightTag='mark'] Tag to use for the highlighted text. - * @property {import('highlight-words-core').FindAllArgs['sanitize']} [sanitize] Custom `santize` function to pass to `highlight-words-core`. - * @property {string[]} [searchWords=[]] Words to search for and highlight. - * @property {string} [unhighlightClassName=''] Classname to apply to unhighlighted text. - * @property {import('react').AllHTMLAttributes['style']} [unhighlightStyle] Style to apply to unhighlighted text. + * @property {string} [activeClassName=''] Classname for active highlighted areas. + * @property {number} [activeIndex=-1] The index of the active highlighted area. + * @property {import('react').AllHTMLAttributes['style']} [activeStyle] Styles to apply to the active highlighted area. + * @property {boolean} [autoEscape] Whether to automatically escape text. + * @property {boolean} [caseSensitive=false] Whether to highlight in a case-sensitive manner. + * @property {string} children Children to highlight. + * @property {import('highlight-words-core').FindAllArgs['findChunks']} [findChunks] Custom `findChunks` function to pass to `highlight-words-core`. + * @property {string | Record} [highlightClassName=''] Classname to apply to highlighted text or a Record of classnames to apply to given text (which should be the key). + * @property {import('react').AllHTMLAttributes['style']} [highlightStyle={}] Styles to apply to highlighted text. + * @property {keyof JSX.IntrinsicElements} [highlightTag='mark'] Tag to use for the highlighted text. + * @property {import('highlight-words-core').FindAllArgs['sanitize']} [sanitize] Custom `santize` function to pass to `highlight-words-core`. + * @property {string[]} [searchWords=[]] Words to search for and highlight. + * @property {string} [unhighlightClassName=''] Classname to apply to unhighlighted text. + * @property {import('react').AllHTMLAttributes['style']} [unhighlightStyle] Style to apply to unhighlighted text. */ /** diff --git a/packages/components/src/toolbar/index.js b/packages/components/src/toolbar/index.js index 3bb887cc1fd33..b4e88f946911d 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/truncate/utils.js b/packages/components/src/truncate/utils.js index 8ac7e5a11935d..0e2e2d3601343 100644 --- a/packages/components/src/truncate/utils.js +++ b/packages/components/src/truncate/utils.js @@ -59,7 +59,7 @@ export function truncateMiddle( word, headLength, tailLength, ellipsis ) { /** * - * @param {string} words + * @param {string} words * @param {typeof TRUNCATE_DEFAULT_PROPS} props */ export function truncateContent( words = '', props ) { diff --git a/packages/components/src/ui/card/body.js b/packages/components/src/ui/card/body.js index 359876c3a7de2..98f8e436cacf6 100644 --- a/packages/components/src/ui/card/body.js +++ b/packages/components/src/ui/card/body.js @@ -18,7 +18,7 @@ import * as styles from './styles'; /** * @param {import('../context').PolymorphicComponentProps} props - * @param {import('react').Ref} forwardedRef + * @param {import('react').Ref} forwardedRef */ function CardBody( props, forwardedRef ) { const { className, scrollable = true, ...otherProps } = useContextSystem( diff --git a/packages/components/src/ui/card/component.js b/packages/components/src/ui/card/component.js index 725808d9f249c..2ffbc112a59f8 100644 --- a/packages/components/src/ui/card/component.js +++ b/packages/components/src/ui/card/component.js @@ -20,7 +20,7 @@ import CONFIG from '../../utils/config-values'; /** * @param {import('../context').PolymorphicComponentProps} props - * @param {import('react').Ref} forwardedRef + * @param {import('react').Ref} forwardedRef */ function Card( props, forwardedRef ) { const { children, elevation, isRounded = true, ...otherProps } = useCard( diff --git a/packages/components/src/ui/card/footer.js b/packages/components/src/ui/card/footer.js index f31a9e5510ace..172e5814341fa 100644 --- a/packages/components/src/ui/card/footer.js +++ b/packages/components/src/ui/card/footer.js @@ -17,7 +17,7 @@ import * as styles from './styles'; /** * @param {import('../context').PolymorphicComponentProps} props - * @param {import('react').Ref} forwardedRef + * @param {import('react').Ref} forwardedRef */ function CardFooter( props, forwardedRef ) { const { diff --git a/packages/components/src/ui/card/header.js b/packages/components/src/ui/card/header.js index bf1ba57260686..59c80f3251c8b 100644 --- a/packages/components/src/ui/card/header.js +++ b/packages/components/src/ui/card/header.js @@ -17,7 +17,7 @@ import * as styles from './styles'; /** * @param {import('../context').PolymorphicComponentProps} props - * @param {import('react').Ref} forwardedRef + * @param {import('react').Ref} forwardedRef */ function CardHeader( props, forwardedRef ) { const { className, size = 'medium', ...otherProps } = useContextSystem( diff --git a/packages/components/src/ui/card/inner-body.js b/packages/components/src/ui/card/inner-body.js index ab12a97e020ed..88bbfb29a1844 100644 --- a/packages/components/src/ui/card/inner-body.js +++ b/packages/components/src/ui/card/inner-body.js @@ -12,7 +12,7 @@ import * as styles from './styles'; /** * @param {import('../context').PolymorphicComponentProps<{}, 'div'>} props - * @param {import('react').Ref} forwardedRef + * @param {import('react').Ref} forwardedRef */ function CardInnerBody( props, forwardedRef ) { const { className, ...otherProps } = useContextSystem( diff --git a/packages/components/src/ui/context/context-connect.js b/packages/components/src/ui/context/context-connect.js index 6f6c90f24123b..9b5358461cb49 100644 --- a/packages/components/src/ui/context/context-connect.js +++ b/packages/components/src/ui/context/context-connect.js @@ -25,10 +25,10 @@ import { getStyledClassNameFromKey } from './get-styled-class-name-from-key'; * component wrappers. * * @template {import('./polymorphic-component').PolymorphicComponentProps<{}, any>} P - * @param {(props: P, ref: import('react').Ref) => JSX.Element | null} Component The component to register into the Context system. - * @param {string} namespace The namespace to register the component under. - * @param {Object} options - * @param {boolean} [options.memo=false] + * @param {(props: P, ref: import('react').Ref) => JSX.Element | null} Component The component to register into the Context system. + * @param {string} namespace The namespace to register the component under. + * @param {Object} options + * @param {boolean} [options.memo=false] * @return {import('./polymorphic-component').PolymorphicComponent, import('./polymorphic-component').PropsFromPolymorphicComponentProps

    >} The connected PolymorphicComponent */ export function contextConnect( Component, namespace, options = {} ) { @@ -102,7 +102,7 @@ export function getConnectNamespace( Component ) { * Checks to see if a component is connected within the Context system. * * @param {import('react').ReactNode} Component The component to retrieve a namespace from. - * @param {Array|string} match The namespace to check. + * @param {Array|string} match The namespace to check. * @return {boolean} The result. */ export function hasConnectNamespace( Component, match ) { diff --git a/packages/components/src/ui/context/context-system-provider.js b/packages/components/src/ui/context/context-system-provider.js index 299d1fe29192c..739ec9beeb8c9 100644 --- a/packages/components/src/ui/context/context-system-provider.js +++ b/packages/components/src/ui/context/context-system-provider.js @@ -27,7 +27,7 @@ export const useComponentsContext = () => useContext( ComponentsContext ); /** * Consolidates incoming ContextSystem values with a (potential) parent ContextSystem value. * - * @param {Object} props + * @param {Object} props * @param {Record} props.value * @return {Record} The consolidated value. */ @@ -72,9 +72,9 @@ function useContextSystemBridge( { value } ) { * ``` * * @template {Record} T - * @param {Object} options + * @param {Object} options * @param {import('react').ReactNode} options.children Children to render. - * @param {T} options.value Props to render into connected components. + * @param {T} options.value Props to render into connected components. * @return {JSX.Element} A Provider wrapped component. */ const BaseContextSystemProvider = ( { children, value } ) => { diff --git a/packages/components/src/ui/context/get-styled-class-name-from-key.ts b/packages/components/src/ui/context/get-styled-class-name-from-key.ts index 76dba53001d82..ec92ea79a3251 100644 --- a/packages/components/src/ui/context/get-styled-class-name-from-key.ts +++ b/packages/components/src/ui/context/get-styled-class-name-from-key.ts @@ -7,7 +7,7 @@ import memoize from 'memize'; /** * Generates the connected component CSS className based on the namespace. * - * @param namespace The name of the connected component. + * @param namespace The name of the connected component. * @return The generated CSS className. */ function getStyledClassName( namespace: string ): string { diff --git a/packages/components/src/ui/context/use-context-system.js b/packages/components/src/ui/context/use-context-system.js index 06acef66d1ee5..d6f399f60dc6d 100644 --- a/packages/components/src/ui/context/use-context-system.js +++ b/packages/components/src/ui/context/use-context-system.js @@ -25,7 +25,7 @@ import { getStyledClassNameFromKey } from './get-styled-class-name-from-key'; * These derived props are then consolidated with incoming component props. * * @template {{ className?: string }} P - * @param {P} props Incoming props from the component. + * @param {P} props Incoming props from the component. * @param {string} namespace The namespace to register and to derive context props from. * @return {ConnectedProps

    } The connected props. */ diff --git a/packages/components/src/ui/control-group/component.js b/packages/components/src/ui/control-group/component.js index 7ea82f0138711..b1b82c581cdfd 100644 --- a/packages/components/src/ui/control-group/component.js +++ b/packages/components/src/ui/control-group/component.js @@ -12,7 +12,7 @@ import { contextConnect } from '../context'; /** * @param {import('../context').PolymorphicComponentProps} props - * @param {import('react').Ref} forwardedRef + * @param {import('react').Ref} forwardedRef */ function ControlGroup( props, forwardedRef ) { const { diff --git a/packages/components/src/ui/form-group/form-group.js b/packages/components/src/ui/form-group/form-group.js index 33a16482eb308..9885aa63d2447 100644 --- a/packages/components/src/ui/form-group/form-group.js +++ b/packages/components/src/ui/form-group/form-group.js @@ -9,7 +9,7 @@ import { useFormGroup } from './use-form-group'; /** * @param {import('../context').PolymorphicComponentProps} props - * @param {import('react').Ref} forwardedRef + * @param {import('react').Ref} forwardedRef */ function FormGroup( props, forwardedRef ) { const { contentProps, horizontal, ...otherProps } = useFormGroup( props ); diff --git a/packages/components/src/ui/popover/component.js b/packages/components/src/ui/popover/component.js index 4d0fe390962de..83c01e42bdcea 100644 --- a/packages/components/src/ui/popover/component.js +++ b/packages/components/src/ui/popover/component.js @@ -22,7 +22,7 @@ import { useUpdateEffect } from '../../utils/hooks'; /** * * @param {import('../context').PolymorphicComponentProps} props - * @param {import('react').Ref} forwardedRef + * @param {import('react').Ref} forwardedRef */ function Popover( props, forwardedRef ) { const { diff --git a/packages/components/src/ui/popover/content.js b/packages/components/src/ui/popover/content.js index 6356049bb98c1..f65b7c81760a5 100644 --- a/packages/components/src/ui/popover/content.js +++ b/packages/components/src/ui/popover/content.js @@ -17,7 +17,7 @@ import { contextConnect, useContextSystem } from '../context'; /** * * @param {import('../context').PolymorphicComponentProps} props - * @param {import('react').Ref} forwardedRef + * @param {import('react').Ref} forwardedRef */ function PopoverContent( props, forwardedRef ) { const { diff --git a/packages/components/src/ui/spinner/component.js b/packages/components/src/ui/spinner/component.js index d5c4ed3f69b4d..12cb30f0d712b 100644 --- a/packages/components/src/ui/spinner/component.js +++ b/packages/components/src/ui/spinner/component.js @@ -9,15 +9,15 @@ import { COLORS } from '../../utils/colors-values'; /* eslint-disable jsdoc/valid-types */ /** * @typedef Props - * @property {import('react').CSSProperties['color']} [color] Color of `Spinner`. - * @property {number} [size=16] Size of `Spinner`. + * @property {import('react').CSSProperties['color']} [color] Color of `Spinner`. + * @property {number} [size=16] Size of `Spinner`. */ /* eslint-enable jsdoc/valid-types */ /** * * @param {import('../context').PolymorphicComponentProps} props - * @param {import('react').Ref} forwardedRef + * @param {import('react').Ref} forwardedRef */ function Spinner( props, forwardedRef ) { const { diff --git a/packages/components/src/ui/tooltip/component.js b/packages/components/src/ui/tooltip/component.js index 059872e61d88e..f618f4633d48f 100644 --- a/packages/components/src/ui/tooltip/component.js +++ b/packages/components/src/ui/tooltip/component.js @@ -19,7 +19,7 @@ import { TooltipShortcut } from './styles'; /** * @param {import('../context').PolymorphicComponentProps} props - * @param {import('react').Ref} forwardedRef + * @param {import('react').Ref} forwardedRef */ function Tooltip( props, forwardedRef ) { const { diff --git a/packages/components/src/ui/tooltip/content.js b/packages/components/src/ui/tooltip/content.js index c022c7d52184b..9aef22e721f22 100644 --- a/packages/components/src/ui/tooltip/content.js +++ b/packages/components/src/ui/tooltip/content.js @@ -18,7 +18,7 @@ const { TooltipPopoverView } = styles; /** * * @param {import('../context').PolymorphicComponentProps} props - * @param {import('react').Ref} forwardedRef + * @param {import('react').Ref} forwardedRef */ function TooltipContent( props, forwardedRef ) { const { children, className, ...otherProps } = useContextSystem( diff --git a/packages/components/src/ui/utils/colors.js b/packages/components/src/ui/utils/colors.js index fb9fc559f6d6e..db911a94eb71d 100644 --- a/packages/components/src/ui/utils/colors.js +++ b/packages/components/src/ui/utils/colors.js @@ -71,7 +71,7 @@ const getComputedBackgroundColor = memoize( _getComputedBackgroundColor ); /** * Get the text shade optimized for readability, based on a background color. * - * @param {string | unknown} backgroundColor The background color. + * @param {string | unknown} backgroundColor The background color. * * @return {string} The optimized text color (black or white). */ diff --git a/packages/components/src/ui/utils/create-component.tsx b/packages/components/src/ui/utils/create-component.tsx index 4cf21c2352751..fe71033f40ae9 100644 --- a/packages/components/src/ui/utils/create-component.tsx +++ b/packages/components/src/ui/utils/create-component.tsx @@ -31,11 +31,11 @@ interface Options< /** * Factory that creates a React component from a hook * - * @param options - * @param options.as The element to render for the component. - * @param options.name The name of the component. - * @param options.useHook The hook to use for the component - * @param options.memo Whether to memo the component. + * @param options + * @param options.as The element to render for the component. + * @param options.name The name of the component. + * @param options.useHook The hook to use for the component + * @param options.memo Whether to memo the component. * @return A polymorphic component that uses the hook to process props. */ export const createComponent = < diff --git a/packages/components/src/ui/utils/get-valid-children.ts b/packages/components/src/ui/utils/get-valid-children.ts index cd16f9afa85e1..de738e2fe0018 100644 --- a/packages/components/src/ui/utils/get-valid-children.ts +++ b/packages/components/src/ui/utils/get-valid-children.ts @@ -12,7 +12,7 @@ import { Children, isValidElement } from '@wordpress/element'; /** * Gets a collection of available children elements from a React component's children prop. * - * @param children + * @param children * * @return An array of available children. */ diff --git a/packages/components/src/ui/utils/use-instance-id.js b/packages/components/src/ui/utils/use-instance-id.js index 5520c9bbe127f..882334327d77f 100644 --- a/packages/components/src/ui/utils/use-instance-id.js +++ b/packages/components/src/ui/utils/use-instance-id.js @@ -27,8 +27,8 @@ function createId( object ) { /** * Provides a unique instance ID. * - * @param {Object} object Object reference to create an id for. - * @param {string} prefix Prefix for the unique id. + * @param {Object} object Object reference to create an id for. + * @param {string} prefix Prefix for the unique id. * @param {string | number} [preferredId=''] Default ID to use. * @return {string | number} The unique instance id. */ diff --git a/packages/components/src/unit-control/index.js b/packages/components/src/unit-control/index.js index c3806baf2f75d..9acd96e82aff2 100644 --- a/packages/components/src/unit-control/index.js +++ b/packages/components/src/unit-control/index.js @@ -126,7 +126,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 b9981dae6d2ce..6999a83c2d6ef 100644 --- a/packages/components/src/unit-control/utils.js +++ b/packages/components/src/unit-control/utils.js @@ -149,7 +149,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. */ @@ -172,8 +172,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 = ALL_CSS_UNITS ) { @@ -201,10 +201,10 @@ export function parseUnit( initialValue, units = ALL_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 ) { @@ -245,7 +245,7 @@ export function parseA11yLabelForUnit( unit ) { * 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/components/src/utils/browsers.js b/packages/components/src/utils/browsers.js index 1960eccebfdf7..54bed9d519ae7 100644 --- a/packages/components/src/utils/browsers.js +++ b/packages/components/src/utils/browsers.js @@ -5,8 +5,8 @@ import { css } from 'emotion'; /* eslint-disable jsdoc/no-undefined-types */ /** - * @param {TemplateStringsArray} strings - * @param {import('create-emotion').Interpolation[]} interpolations + * @param {TemplateStringsArray} strings + * @param {import('create-emotion').Interpolation[]} interpolations */ export function firefoxOnly( strings, ...interpolations ) { const interpolatedStyles = css( strings, ...interpolations ); @@ -19,8 +19,8 @@ export function firefoxOnly( strings, ...interpolations ) { } /** - * @param {TemplateStringsArray} strings - * @param {import('create-emotion').Interpolation[]} interpolations + * @param {TemplateStringsArray} strings + * @param {import('create-emotion').Interpolation[]} interpolations */ export function safariOnly( strings, ...interpolations ) { const interpolatedStyles = css( strings, ...interpolations ); diff --git a/packages/components/src/utils/colors.js b/packages/components/src/utils/colors.js index 83b81799d5203..be47494012231 100644 --- a/packages/components/src/utils/colors.js +++ b/packages/components/src/utils/colors.js @@ -7,7 +7,7 @@ import tinycolor from 'tinycolor2'; * Generating a CSS compliant 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 774e5b15863c0..18a8174e68bb5 100644 --- a/packages/components/src/utils/hooks/use-controlled-state.js +++ b/packages/components/src/utils/hooks/use-controlled-state.js @@ -43,8 +43,8 @@ const defaultOptions = { * * @template T * - * @param {T | undefined} currentState The current value. - * @param {Options} [options=defaultOptions] Additional options for the hook. + * @param {T | undefined} currentState The current value. + * @param {Options} [options=defaultOptions] Additional options for the hook. * * @return {[T | "", (nextState: T) => void]} 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 d241bfcdee5a4..9a598ab6a29d3 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 662010f0c1900..76a3d66ed88ec 100644 --- a/packages/components/src/utils/math.js +++ b/packages/components/src/utils/math.js @@ -65,9 +65,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. */ diff --git a/packages/components/src/utils/values.js b/packages/components/src/utils/values.js index 5bf94b6ece841..8a609a3df7161 100644 --- a/packages/components/src/utils/values.js +++ b/packages/components/src/utils/values.js @@ -33,8 +33,8 @@ export function isValueEmpty( value ) { * * @template T * - * @param {Array} values Values to derive from. - * @param {T} fallbackValue Fallback value if there are no defined values. + * @param {Array} values Values to derive from. + * @param {T} fallbackValue Fallback value if there are no defined values. * @return {T} A defined value or the fallback value. */ export function getDefinedValue( values = [], fallbackValue ) { diff --git a/packages/components/src/visually-hidden/index.js b/packages/components/src/visually-hidden/index.js index 208203a592c3b..d320002f4fa27 100644 --- a/packages/components/src/visually-hidden/index.js +++ b/packages/components/src/visually-hidden/index.js @@ -28,8 +28,8 @@ import { renderAsRenderProps } from './utils'; * VisuallyHidden component to render text out non-visually * for use in devices such as a screen reader. * - * @template {keyof JSX.IntrinsicElements | import('react').JSXElementConstructor} T T - * @param {Props} props + * @template {keyof JSX.IntrinsicElements | import('react').JSXElementConstructor} T + * @param {Props} props * @param {import('react').Ref} forwardedRef * @return {JSX.Element} Element */ diff --git a/packages/components/src/visually-hidden/utils.js b/packages/components/src/visually-hidden/utils.js index d8be9e759c614..d5eabd100461c 100644 --- a/packages/components/src/visually-hidden/utils.js +++ b/packages/components/src/visually-hidden/utils.js @@ -1,7 +1,7 @@ /** * @template {keyof JSX.IntrinsicElements | import('react').JSXElementConstructor} T * @typedef OwnProps - * @property {T} [as='div'] Component to render + * @property {T} [as='div'] Component to render * @property {import('react').ReactNode | ((props: import('react').ComponentProps) => JSX.Element) } [children] Children or render props function */ diff --git a/packages/compose/src/higher-order/if-condition/index.tsx b/packages/compose/src/higher-order/if-condition/index.tsx index e04dd0fc96ee4..732958ec14e85 100644 --- a/packages/compose/src/higher-order/if-condition/index.tsx +++ b/packages/compose/src/higher-order/if-condition/index.tsx @@ -18,7 +18,7 @@ import type { HigherOrderComponent } from '../../utils/create-higher-order-compo * ; // =>
    bar
    ; * ``` * - * @param predicate Function to test condition. + * @param predicate Function to test condition. * * @return Higher-order component. */ diff --git a/packages/compose/src/higher-order/with-global-events/index.js b/packages/compose/src/higher-order/with-global-events/index.js index a5fec972eeadb..6f6947e1e30f4 100644 --- a/packages/compose/src/higher-order/with-global-events/index.js +++ b/packages/compose/src/higher-order/with-global-events/index.js @@ -32,11 +32,11 @@ const listener = new Listener(); * @deprecated * * @param {Record} eventTypesToHandlers Object with keys of DOM - * event type, the value a - * name of the function on - * the original component's - * instance which handles - * the event. + * event type, the value a + * name of the function on + * the original component's + * instance which handles + * the event. * * @return {any} Higher-order component. */ diff --git a/packages/compose/src/hooks/use-async-list/index.ts b/packages/compose/src/hooks/use-async-list/index.ts index 527142be2033f..bd614ae09d222 100644 --- a/packages/compose/src/hooks/use-async-list/index.ts +++ b/packages/compose/src/hooks/use-async-list/index.ts @@ -7,8 +7,8 @@ import { createQueue } from '@wordpress/priority-queue'; /** * Returns the first items from list that are present on state. * - * @param list New array. - * @param state Current state. + * @param list New array. + * @param state Current state. * @return First items present iin state. */ function getFirstItemsPresentInState< T >( list: T[], state: T[] ): T[] { @@ -30,7 +30,7 @@ function getFirstItemsPresentInState< T >( list: T[], state: T[] ): T[] { * React hook returns an array which items get asynchronously appended from a source array. * This behavior is useful if we want to render a list of items asynchronously for performance reasons. * - * @param list Source array. + * @param list Source array. * @return Async array. */ function useAsyncList< T >( list: T[] ): T[] { diff --git a/packages/compose/src/hooks/use-copy-on-click/index.js b/packages/compose/src/hooks/use-copy-on-click/index.js index 238e2bc35573d..4397e41b72b6c 100644 --- a/packages/compose/src/hooks/use-copy-on-click/index.js +++ b/packages/compose/src/hooks/use-copy-on-click/index.js @@ -15,10 +15,10 @@ import deprecated from '@wordpress/deprecated'; * * @deprecated * - * @param {import('react').RefObject>} ref Reference with the element. - * @param {string|Function} text The text to copy. - * @param {number} [timeout] Optional timeout to reset the returned - * state. 4 seconds by default. + * @param {import('react').RefObject>} ref Reference with the element. + * @param {string|Function} text The text to copy. + * @param {number} [timeout] Optional timeout to reset the returned + * state. 4 seconds by default. * * @return {boolean} Whether or not the text has been copied. Resets after the * timeout. diff --git a/packages/compose/src/hooks/use-copy-to-clipboard/index.js b/packages/compose/src/hooks/use-copy-to-clipboard/index.js index aee08641b9a87..3089915a455e2 100644 --- a/packages/compose/src/hooks/use-copy-to-clipboard/index.js +++ b/packages/compose/src/hooks/use-copy-to-clipboard/index.js @@ -27,9 +27,9 @@ function useUpdatedRef( value ) { /** * Copies the given text to the clipboard when the element is clicked. * - * @param {string | (() => string)} text The text to copy. Use a function if not - * already available and expensive to compute. - * @param {Function} onSuccess Called when to text is copied. + * @param {string | (() => string)} text The text to copy. Use a function if not + * already available and expensive to compute. + * @param {Function} onSuccess Called when to text is copied. * * @return {import('react').Ref} A ref to assign to the target element. */ diff --git a/packages/compose/src/hooks/use-debounce/index.js b/packages/compose/src/hooks/use-debounce/index.js index 2f0c1811ade03..374f20a521a5e 100644 --- a/packages/compose/src/hooks/use-debounce/index.js +++ b/packages/compose/src/hooks/use-debounce/index.js @@ -20,8 +20,8 @@ import { useEffect } from '@wordpress/element'; * * @template {(...args: any[]) => void} TFunc * - * @param {TFunc} fn The function to debounce. - * @param {number} [wait] The number of milliseconds to delay. + * @param {TFunc} fn The function to debounce. + * @param {number} [wait] The number of milliseconds to delay. * @param {import('lodash').DebounceSettings} [options] The options object. * @return {TFunc & import('lodash').Cancelable} Debounced function. */ diff --git a/packages/compose/src/hooks/use-dragging/index.js b/packages/compose/src/hooks/use-dragging/index.js index 3349347d567d7..357419a8c77e5 100644 --- a/packages/compose/src/hooks/use-dragging/index.js +++ b/packages/compose/src/hooks/use-dragging/index.js @@ -9,7 +9,7 @@ import { useCallback, useEffect, useRef, useState } from '@wordpress/element'; import useIsomorphicLayoutEffect from '../use-isomorphic-layout-effect'; /** - * @param {Object} props + * @param {Object} props * @param {(e: MouseEvent) => void} props.onDragStart * @param {(e: MouseEvent) => void} props.onDragMove * @param {(e: MouseEvent) => void} props.onDragEnd diff --git a/packages/compose/src/hooks/use-drop-zone/index.js b/packages/compose/src/hooks/use-drop-zone/index.js index 1f5e032c86049..d2052d1e8c6ef 100644 --- a/packages/compose/src/hooks/use-drop-zone/index.js +++ b/packages/compose/src/hooks/use-drop-zone/index.js @@ -33,14 +33,14 @@ function useFreshRef( value ) { /** * A hook to facilitate drag and drop handling. * - * @param {Object} props Named parameters. - * @param {boolean} props.isDisabled Whether or not to disable the drop zone. - * @param {(e: DragEvent) => void} props.onDragStart Called when dragging has started. - * @param {(e: DragEvent) => void} props.onDragEnter Called when the zone is entered. - * @param {(e: DragEvent) => void} props.onDragOver Called when the zone is moved within. - * @param {(e: DragEvent) => void} props.onDragLeave Called when the zone is left. - * @param {(e: MouseEvent) => void} props.onDragEnd Called when dragging has ended. - * @param {(e: DragEvent) => void} props.onDrop Called when dropping in the zone. + * @param {Object} props Named parameters. + * @param {boolean} props.isDisabled Whether or not to disable the drop zone. + * @param {(e: DragEvent) => void} props.onDragStart Called when dragging has started. + * @param {(e: DragEvent) => void} props.onDragEnter Called when the zone is entered. + * @param {(e: DragEvent) => void} props.onDragOver Called when the zone is moved within. + * @param {(e: DragEvent) => void} props.onDragLeave Called when the zone is left. + * @param {(e: MouseEvent) => void} props.onDragEnd Called when dragging has ended. + * @param {(e: DragEvent) => void} props.onDrop Called when dropping in the zone. * * @return {import('react').RefCallback} Ref callback to be passed to the drop zone element. */ diff --git a/packages/compose/src/hooks/use-focus-outside/index.js b/packages/compose/src/hooks/use-focus-outside/index.js index 2169d4fd83c37..058159b952975 100644 --- a/packages/compose/src/hooks/use-focus-outside/index.js +++ b/packages/compose/src/hooks/use-focus-outside/index.js @@ -84,8 +84,8 @@ function isFocusNormalizedButton( eventTarget ) { * A react hook that can be used to check whether focus has moved outside the * element the event handlers are bound to. * - * @param {EventCallback} onFocusOutside A callback triggered when focus moves outside - * the element the event handlers are bound to. + * @param {EventCallback} onFocusOutside A callback triggered when focus moves outside + * the element the event handlers are bound to. * * @return {FocusOutsideReturnValue} An object containing event handlers. Bind the event handlers * to a wrapping element element to capture when focus moves diff --git a/packages/compose/src/hooks/use-focus-outside/index.native.js b/packages/compose/src/hooks/use-focus-outside/index.native.js index 6c5c35766379f..5796a4308af61 100644 --- a/packages/compose/src/hooks/use-focus-outside/index.native.js +++ b/packages/compose/src/hooks/use-focus-outside/index.native.js @@ -81,8 +81,8 @@ function isFocusNormalizedButton( eventTarget ) { * A react hook that can be used to check whether focus has moved outside the * element the event handlers are bound to. * - * @param {EventCallback} onFocusOutside A callback triggered when focus moves outside - * the element the event handlers are bound to. + * @param {EventCallback} onFocusOutside A callback triggered when focus moves outside + * the element the event handlers are bound to. * * @return {FocusOutsideReturnValue} An object containing event handlers. Bind the event handlers * to a wrapping element element to capture when focus moves diff --git a/packages/compose/src/hooks/use-instance-id/index.js b/packages/compose/src/hooks/use-instance-id/index.js index 5792aaac6e615..30dcc6d4d4c93 100644 --- a/packages/compose/src/hooks/use-instance-id/index.js +++ b/packages/compose/src/hooks/use-instance-id/index.js @@ -26,8 +26,8 @@ function createId( object ) { /** * Provides a unique instance ID. * - * @param {object} object Object reference to create an id for. - * @param {string} [prefix] Prefix for the unique id. + * @param {object} object Object reference to create an id for. + * @param {string} [prefix] Prefix for the unique id. * @param {string} [preferredId=''] Default ID to use. * @return {string | number} The unique instance id. */ diff --git a/packages/compose/src/hooks/use-keyboard-shortcut/index.js b/packages/compose/src/hooks/use-keyboard-shortcut/index.js index 8b6068a436524..6e38ea0ec3121 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 {import('react').RefObject} [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 {import('react').RefObject} [target] React reference to the DOM element used to catch the keyboard event. */ /** * Return true if platform is MacOS. * - * @param {Window} [_window] window object by default; used for DI testing. + * @param {Window} [_window] window object by default; used for DI testing. * * @return {boolean} True if MacOS; false otherwise. */ @@ -43,9 +43,9 @@ function isAppleOS( _window = window ) { * * @see https://craig.is/killing/mice#api.bind for information about the `callback` parameter. * - * @param {string[]|string} shortcuts Keyboard Shortcuts. - * @param {(e: import('mousetrap').ExtendedKeyboardEvent, combo: string) => void} callback Shortcut callback. - * @param {WPKeyboardShortcutConfig} options Shortcut options. + * @param {string[]|string} shortcuts Keyboard Shortcuts. + * @param {(e: import('mousetrap').ExtendedKeyboardEvent, combo: string) => void} callback Shortcut callback. + * @param {WPKeyboardShortcutConfig} options Shortcut options. */ function useKeyboardShortcut( /* eslint-enable jsdoc/valid-types */ diff --git a/packages/compose/src/hooks/use-merge-refs/index.js b/packages/compose/src/hooks/use-merge-refs/index.js index 5b8b353a3b680..468027f8e37d0 100644 --- a/packages/compose/src/hooks/use-merge-refs/index.js +++ b/packages/compose/src/hooks/use-merge-refs/index.js @@ -13,7 +13,7 @@ import { useRef, useCallback, useLayoutEffect } from '@wordpress/element'; /** * @template T * @param {import('react').Ref} ref - * @param {T} value + * @param {T} value */ function assignRef( ref, value ) { if ( typeof ref === 'function' ) { diff --git a/packages/compose/src/hooks/use-ref-effect/index.ts b/packages/compose/src/hooks/use-ref-effect/index.ts index 2b90c964e394e..549cf0ffa5d1c 100644 --- a/packages/compose/src/hooks/use-ref-effect/index.ts +++ b/packages/compose/src/hooks/use-ref-effect/index.ts @@ -23,8 +23,8 @@ import { useCallback, useRef } from '@wordpress/element'; * to be removed. It *is* necessary if you add dependencies because the ref * callback will be called multiple times for the same node. * - * @param callback Callback with ref as argument. - * @param dependencies Dependencies of the callback. + * @param callback Callback with ref as argument. + * @param dependencies Dependencies of the callback. * * @return Ref callback. */ diff --git a/packages/compose/src/hooks/use-throttle/index.js b/packages/compose/src/hooks/use-throttle/index.js index e6596bb6982ce..8ad9589d112de 100644 --- a/packages/compose/src/hooks/use-throttle/index.js +++ b/packages/compose/src/hooks/use-throttle/index.js @@ -17,10 +17,10 @@ import { useEffect } from '@wordpress/element'; * * @see https://docs-lodash.com/v4/throttle/ * - * @template {(...args: any[]) => void} TFunc TFunc + * @template {(...args: any[]) => void} TFunc * - * @param {TFunc} fn The function to throttle. - * @param {number} [wait] The number of milliseconds to throttle invocations to. + * @param {TFunc} fn The function to throttle. + * @param {number} [wait] The number of milliseconds to throttle invocations to. * @param {import('lodash').ThrottleSettings} [options] The options object. See linked documentation for details. * @return {TFunc & import('lodash').Cancelable} Throttled function. */ diff --git a/packages/compose/src/utils/create-higher-order-component/index.ts b/packages/compose/src/utils/create-higher-order-component/index.ts index 025d49e202984..1a96b7913e14f 100644 --- a/packages/compose/src/utils/create-higher-order-component/index.ts +++ b/packages/compose/src/utils/create-higher-order-component/index.ts @@ -32,8 +32,8 @@ export type PropInjectingHigherOrderComponent< TRemovedProps > = < * Given a function mapping a component to an enhanced component and modifier * name, returns the enhanced component augmented with a generated displayName. * - * @param mapComponentToEnhancedComponent Function mapping component to enhanced component. - * @param modifierName Seed name from which to generated display name. + * @param mapComponentToEnhancedComponent Function mapping component to enhanced component. + * @param modifierName Seed name from which to generated display name. * * @return Component class with generated display name assigned. */ diff --git a/packages/core-data/src/actions.js b/packages/core-data/src/actions.js index 364d1d3a68052..d4ccbbd3ae997 100644 --- a/packages/core-data/src/actions.js +++ b/packages/core-data/src/actions.js @@ -57,7 +57,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. */ @@ -141,8 +141,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. */ @@ -237,11 +237,11 @@ export function* deleteEntityRecord( * 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. @@ -694,11 +694,11 @@ export function* saveEditedEntityRecord( kind, name, recordId, options ) { /** * Action triggered to save only specified properties for the entity. * - * @param {string} kind Kind of the entity. - * @param {string} name Name of the entity. - * @param {Object} recordId ID of the record. - * @param {Array} itemsToSave List of entity properties to save. - * @param {Object} options Saving options. + * @param {string} kind Kind of the entity. + * @param {string} name Name of the entity. + * @param {Object} recordId ID of the record. + * @param {Array} itemsToSave List of entity properties to save. + * @param {Object} options Saving options. */ export function* __experimentalSaveSpecifiedEntityEdits( kind, diff --git a/packages/core-data/src/batch/create-batch.js b/packages/core-data/src/batch/create-batch.js index 6009aee86f25c..dbd9073dac36a 100644 --- a/packages/core-data/src/batch/create-batch.js +++ b/packages/core-data/src/batch/create-batch.js @@ -67,7 +67,7 @@ export default function createBatch( processor = defaultProcessor ) { * - The thunk returns a non-promise. * * @param {any|Function} inputOrThunk Input to add or thunk to execute. - + * * @return {Promise|any} If given an input, returns a promise that * is resolved or rejected when the batch is * processed. If given a thunk, returns the return diff --git a/packages/core-data/src/entities.js b/packages/core-data/src/entities.js index 741e6696e3ed0..8e07b4153ab7f 100644 --- a/packages/core-data/src/entities.js +++ b/packages/core-data/src/entities.js @@ -136,7 +136,7 @@ export const kinds = [ * Returns a function to be used to retrieve extra edits to apply before persisting a post type. * * @param {Object} persistedRecord Already persisted Post - * @param {Object} edits Edits. + * @param {Object} edits Edits. * @return {Object} Updated edits. */ export const prePersistPostType = ( persistedRecord, edits ) => { @@ -243,7 +243,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/entity-provider.js b/packages/core-data/src/entity-provider.js index 3af512e04152d..e0ab45b5e5117 100644 --- a/packages/core-data/src/entity-provider.js +++ b/packages/core-data/src/entity-provider.js @@ -134,10 +134,10 @@ export function useEntityProp( kind, type, prop, _id ) { * `BlockEditorProvider` and are intended to be used with it, * or similar components or hooks. * - * @param {string} kind The entity kind. - * @param {string} type The entity type. + * @param {string} kind The entity kind. + * @param {string} type The entity type. * @param {Object} options - * @param {string} [options.id] An entity ID to use instead of the context-provided one. + * @param {string} [options.id] An entity ID to use instead of the context-provided one. * * @return {[WPBlock[], Function, Function]} The block array and setters. */ diff --git a/packages/core-data/src/fetch/__experimental-fetch-link-suggestions.js b/packages/core-data/src/fetch/__experimental-fetch-link-suggestions.js index 625da54932652..add566050d4b3 100644 --- a/packages/core-data/src/fetch/__experimental-fetch-link-suggestions.js +++ b/packages/core-data/src/fetch/__experimental-fetch-link-suggestions.js @@ -21,11 +21,11 @@ import { __ } from '@wordpress/i18n'; /** * @typedef WPLinkSearchOptions * - * @property {boolean} [isInitialSuggestions] Displays initial search suggestions, when true. - * @property {WPLinkSearchType} [type] Filters by search type. - * @property {string} [subtype] Slug of the post-type or taxonomy. - * @property {number} [page] Which page of results to return. - * @property {number} [perPage] Search results per page. + * @property {boolean} [isInitialSuggestions] Displays initial search suggestions, when true. + * @property {WPLinkSearchType} [type] Filters by search type. + * @property {string} [subtype] Slug of the post-type or taxonomy. + * @property {number} [page] Which page of results to return. + * @property {number} [perPage] Search results per page. */ /** diff --git a/packages/core-data/src/fetch/__experimental-fetch-remote-url-data.js b/packages/core-data/src/fetch/__experimental-fetch-remote-url-data.js index fd2d84d0e6c9d..93602fe4149b1 100644 --- a/packages/core-data/src/fetch/__experimental-fetch-remote-url-data.js +++ b/packages/core-data/src/fetch/__experimental-fetch-remote-url-data.js @@ -7,7 +7,7 @@ import { addQueryArgs, prependHTTP } from '@wordpress/url'; /** * @typedef WPRemoteUrlData * - * @property {string} title contents of the remote URL's `` tag. + * @property {string} title contents of the remote URL's `<title>` tag. */ /** @@ -15,7 +15,7 @@ import { addQueryArgs, prependHTTP } from '@wordpress/url'; * eg: <title> tag, favicon...etc. * * @async - * @param {string} url + * @param {string} url * * @example * ```js diff --git a/packages/core-data/src/locks/reducer.js b/packages/core-data/src/locks/reducer.js index 6a29de6a3ffab..878313b67b341 100644 --- a/packages/core-data/src/locks/reducer.js +++ b/packages/core-data/src/locks/reducer.js @@ -14,8 +14,8 @@ const DEFAULT_STATE = { /** * Reducer returning locks. * - * @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/queried-data/actions.js b/packages/core-data/src/queried-data/actions.js index c88eb364ea845..15984e8ac441d 100644 --- a/packages/core-data/src/queried-data/actions.js +++ b/packages/core-data/src/queried-data/actions.js @@ -23,10 +23,10 @@ export function receiveItems( items, edits ) { * 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<string,boolean>} state Current state. - * @param {Object} action Dispatched action. + * @param {Object} action Dispatched action. * * @return {Object<string,boolean>} Next state. */ diff --git a/packages/core-data/src/reducer.js b/packages/core-data/src/reducer.js index 51c43a529d9ab..6ce70d6a1b465 100644 --- a/packages/core-data/src/reducer.js +++ b/packages/core-data/src/reducer.js @@ -167,7 +167,7 @@ export function themeSupports( state = {}, action ) { * - Editing * - Saving * - * @param {Object} entityConfig Entity config. + * @param {Object} entityConfig Entity config. * * @return {Function} Reducer. */ @@ -523,8 +523,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. */ @@ -543,8 +543,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 e9aabbae6ce0d..ac06a719b2f0a 100644 --- a/packages/core-data/src/resolvers.js +++ b/packages/core-data/src/resolvers.js @@ -163,9 +163,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 ); @@ -272,7 +272,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 { @@ -385,7 +385,7 @@ export function* getAutosave( postType, postId ) { /** * Retrieve the frontend template used for a given link. * - * @param {string} link Link. + * @param {string} link Link. */ export function* __experimentalGetTemplateForLink( link ) { // Ideally this should be using an apiFetch call diff --git a/packages/core-data/src/selectors.js b/packages/core-data/src/selectors.js index a7f8193164611..56f11f2fce860 100644 --- a/packages/core-data/src/selectors.js +++ b/packages/core-data/src/selectors.js @@ -69,7 +69,7 @@ export function getAuthors( state, query ) { * Returns all available authors. * * @param {Object} state Data state. - * @param {number} id The author id. + * @param {number} id The author id. * * @return {Array} Authors list. */ @@ -108,7 +108,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 {Array<Object>} Array of entities with config matching kind. @@ -120,7 +120,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. * @@ -180,10 +180,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. */ @@ -200,10 +200,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. */ @@ -566,7 +566,7 @@ export function hasRedo( state ) { * * @param {Object} state Data state. * - * @return {Object} The current theme. + * @return {Object} The current theme. */ export function getCurrentTheme( state ) { return state.themes[ state.currentTheme ]; @@ -577,7 +577,7 @@ export function getCurrentTheme( state ) { * * @param {Object} state Data state. * - * @return {*} Index data. + * @return {*} Index data. */ export function getThemeSupports( state ) { return state.themeSupports; @@ -586,8 +586,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. */ @@ -602,8 +602,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. */ @@ -625,10 +625,10 @@ export function isPreviewEmbedFallback( state, url ) { * * 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. @@ -676,7 +676,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/customize-widgets/src/components/customize-widgets/use-clear-selected-block.js b/packages/customize-widgets/src/components/customize-widgets/use-clear-selected-block.js index 96205e71695c0..a243c4006a9ea 100644 --- a/packages/customize-widgets/src/components/customize-widgets/use-clear-selected-block.js +++ b/packages/customize-widgets/src/components/customize-widgets/use-clear-selected-block.js @@ -19,7 +19,7 @@ import { store as blockEditorStore } from '@wordpress/block-editor'; * not by explicitly focusing outside the editor, hence no need for clearing. * * @param {Object} sidebarControl The sidebar control instance. - * @param {Object} popoverRef The ref object of the popover node container. + * @param {Object} popoverRef The ref object of the popover node container. */ export default function useClearSelectedBlock( sidebarControl, popoverRef ) { const { hasSelectedBlock, hasMultiSelection } = useSelect( diff --git a/packages/customize-widgets/src/store/reducer.js b/packages/customize-widgets/src/store/reducer.js index b3087affe1154..8076cc26df943 100644 --- a/packages/customize-widgets/src/store/reducer.js +++ b/packages/customize-widgets/src/store/reducer.js @@ -28,8 +28,8 @@ const createWithInitialState = ( initialState ) => ( reducer ) => { /** * 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 {Object} Updated state. */ 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 2f6560b3aefd7..e8ed87827206d 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 @@ -20,11 +20,11 @@ import useRegistry from '../registry-provider/use-registry'; * * Currently this is an internal api only and is implemented by `withDispatch` * - * @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 {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. * @return {Object} An object mapping props to functions created by the passed * in dispatchMap. */ diff --git a/packages/data/src/components/use-select/index.js b/packages/data/src/components/use-select/index.js index b9249c671f328..54476fc229bbb 100644 --- a/packages/data/src/components/use-select/index.js +++ b/packages/data/src/components/use-select/index.js @@ -27,20 +27,20 @@ const renderQueue = createQueue(); * In general, this custom React hook follows the * [rules of hooks](https://reactjs.org/docs/hooks-rules.html). * - * @param {Function|WPDataStore|string} _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. - * When a store key is passed, all selectors for - * the store will be returned. This is only meant - * for usage of these selectors in event - * callbacks, not for data needed to create the - * element tree. - * @param {Array} deps If provided, this memoizes the mapSelect so the - * same `mapSelect` is invoked on every state - * change unless the dependencies change. + * @param {Function|WPDataStore|string} _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. + * When a store key is passed, all selectors for + * the store will be returned. This is only meant + * for usage of these selectors in event + * callbacks, not for data needed to create the + * element tree. + * @param {Array} deps If provided, this memoizes the mapSelect so the + * same `mapSelect` is invoked on every state + * change unless the dependencies change. * * @example * ```js diff --git a/packages/data/src/components/with-select/index.js b/packages/data/src/components/with-select/index.js index 60972896b10b6..994dfb980bbfc 100644 --- a/packages/data/src/components/with-select/index.js +++ b/packages/data/src/components/with-select/index.js @@ -13,8 +13,8 @@ import useSelect from '../use-select'; * selectors. * * @param {Function} mapSelectToProps Function called on every state change, - * expected to return object of props to - * merge with the component's own props. + * expected to return object of props to + * merge with the component's own props. * * @example * ```js diff --git a/packages/data/src/controls.js b/packages/data/src/controls.js index ec7e78a2956d8..1d8f090fbcb5e 100644 --- a/packages/data/src/controls.js +++ b/packages/data/src/controls.js @@ -41,9 +41,9 @@ function select( storeKey, selectorName, ...args ) { * selectors that may have a resolver. In such case, it will return a `Promise` that resolves * after the selector finishes resolving, with the final result value. * - * @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 selector. + * @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 selector. * * @example * ```js @@ -65,9 +65,9 @@ function resolveSelect( 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/factory.js b/packages/data/src/factory.js index 400f4ffe15c0a..51d4420dda5a6 100644 --- a/packages/data/src/factory.js +++ b/packages/data/src/factory.js @@ -31,7 +31,7 @@ * with a store. * * @param {Function} registrySelector Function receiving a registry `select` - * function and returning a state selector. + * function and returning a state selector. * * @return {Function} Registry selector that can be registered with a store. */ diff --git a/packages/data/src/index.js b/packages/data/src/index.js index 1a2235ba99fff..666c6d3d12b72 100644 --- a/packages/data/src/index.js +++ b/packages/data/src/index.js @@ -71,8 +71,8 @@ export { plugins }; * register( store ); * ``` * - * @return {Function} A reducer that invokes every reducer inside the reducers - * object, and constructs a state object with the same shape. + * @return {Function} A reducer that invokes every reducer inside the reducers + * object, and constructs a state object with the same shape. */ export { combineReducers }; diff --git a/packages/data/src/redux-store/index.js b/packages/data/src/redux-store/index.js index 371d1d470bc52..d15f60b4cced6 100644 --- a/packages/data/src/redux-store/index.js +++ b/packages/data/src/redux-store/index.js @@ -70,10 +70,10 @@ function createResolversCache() { * } ); * ``` * - * @param {string} key Unique namespace identifier. - * @param {WPDataReduxStoreConfig} options Registered store options, with properties - * describing reducer, actions, selectors, - * and resolvers. + * @param {string} key Unique namespace identifier. + * @param {WPDataReduxStoreConfig} options Registered store options, with properties + * describing reducer, actions, selectors, + * and resolvers. * * @return {WPDataStore} Store Object. */ @@ -197,12 +197,12 @@ export default function createReduxStore( key, options ) { /** * Creates a redux store for a namespace. * - * @param {string} key Unique namespace identifier. - * @param {Object} options Registered store options, with properties - * describing reducer, actions, selectors, - * and resolvers. - * @param {WPDataRegistry} registry Registry reference. - * @param {Object} thunkArgs Argument object for the thunk middleware. + * @param {string} key Unique namespace identifier. + * @param {Object} options Registered store options, with properties + * describing reducer, actions, selectors, + * and resolvers. + * @param {WPDataRegistry} registry Registry reference. + * @param {Object} thunkArgs Argument object for the thunk middleware. * @return {Object} Newly created redux store. */ function instantiateReduxStore( key, options, registry, thunkArgs ) { @@ -289,9 +289,10 @@ 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. - * @return {Object} Actions mapped to the redux store provided. + * @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 ) { const createBoundAction = ( action ) => ( ...args ) => { @@ -306,7 +307,8 @@ function mapActions( actions, store ) { * * @param {Object} selectors Selectors to map. * @param {Object} store The redux store the selectors select from. - * @return {Object} Selectors mapped to their resolution functions. + * + * @return {Object} Selectors mapped to their resolution functions. */ function mapResolveSelectors( selectors, store ) { return mapValues( @@ -432,7 +434,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/redux-store/metadata/actions.js b/packages/data/src/redux-store/metadata/actions.js index 2b4cd072530a5..0dc70aa800366 100644 --- a/packages/data/src/redux-store/metadata/actions.js +++ b/packages/data/src/redux-store/metadata/actions.js @@ -38,7 +38,7 @@ export function finishResolution( selectorName, args ) { * * @param {string} selectorName Name of selector for which resolver triggered. * @param {...*} args Array of arguments to associate for uniqueness, each item - * is associated to a resolution. + * is associated to a resolution. * * @return {Object} Action object. */ @@ -56,7 +56,7 @@ export function startResolutions( selectorName, args ) { * * @param {string} selectorName Name of selector for which resolver triggered. * @param {...*} args Array of arguments to associate for uniqueness, each item - * is associated to a resolution. + * is associated to a resolution. * * @return {Object} Action object. */ diff --git a/packages/data/src/redux-store/metadata/reducer.js b/packages/data/src/redux-store/metadata/reducer.js index b762c1a022e39..8f59e72ad0384 100644 --- a/packages/data/src/redux-store/metadata/reducer.js +++ b/packages/data/src/redux-store/metadata/reducer.js @@ -54,8 +54,8 @@ const subKeysIsResolved = onSubKey( 'selectorName' )( * * selectorName -> EquivalentKeyMap<Array, boolean> * - * @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/redux-store/metadata/selectors.js b/packages/data/src/redux-store/metadata/selectors.js index 34217edcedd10..4983f049c8442 100644 --- a/packages/data/src/redux-store/metadata/selectors.js +++ b/packages/data/src/redux-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 43b6ee1cd32c8..151bdd3d6d095 100644 --- a/packages/data/src/registry.js +++ b/packages/data/src/registry.js @@ -61,9 +61,9 @@ 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. + * @return {Function} Unsubscribe function. */ const subscribe = ( listener ) => { listeners.push( listener ); @@ -229,8 +229,8 @@ export function createRegistry( storeConfigs = {}, parent = null ) { /** * Registers a standard `@wordpress/data` store. * - * @param {string} storeName Unique namespace identifier. - * @param {Object} options Store description (reducer, actions, selectors, resolvers). + * @param {string} storeName Unique namespace identifier. + * @param {Object} options Store description (reducer, actions, selectors, resolvers). * * @return {Object} Registered store object. */ diff --git a/packages/date/src/index.js b/packages/date/src/index.js index 6487a17be1b23..8e9c46e6de947 100644 --- a/packages/date/src/index.js +++ b/packages/date/src/index.js @@ -18,9 +18,9 @@ import 'moment-timezone/moment-timezone-utils'; /** * @typedef FormatsConfig - * @property {string} time Time format. - * @property {string} date Date format. - * @property {string} datetime Datetime format. + * @property {string} time Time format. + * @property {string} date Date format. + * @property {string} datetime Datetime format. * @property {string} datetimeAbbreviated Abbreviated datetime format. */ @@ -28,26 +28,26 @@ import 'moment-timezone/moment-timezone-utils'; * @typedef TimezoneConfig * @property {string} offset Offset setting. * @property {string} string The timezone as a string (e.g., `'America/Los_Angeles'`). - * @property {string} abbr Abbreviation for the timezone. + * @property {string} abbr Abbreviation for the timezone. */ /* eslint-disable jsdoc/valid-types */ /** * @typedef L10nSettings - * @property {string} locale Moment locale. - * @property {MomentLocaleSpecification['months']} months Locale months. - * @property {MomentLocaleSpecification['monthsShort']} monthsShort Locale months short. - * @property {MomentLocaleSpecification['weekdays']} weekdays Locale weekdays. + * @property {string} locale Moment locale. + * @property {MomentLocaleSpecification['months']} months Locale months. + * @property {MomentLocaleSpecification['monthsShort']} monthsShort Locale months short. + * @property {MomentLocaleSpecification['weekdays']} weekdays Locale weekdays. * @property {MomentLocaleSpecification['weekdaysShort']} weekdaysShort Locale weekdays short. - * @property {MeridiemConfig} meridiem Meridiem config. - * @property {MomentLocaleSpecification['relativeTime']} relative Relative time config. + * @property {MeridiemConfig} meridiem Meridiem config. + * @property {MomentLocaleSpecification['relativeTime']} relative Relative time config. */ /* eslint-enable jsdoc/valid-types */ /** * @typedef DateSettings - * @property {L10nSettings} l10n Localization settings. - * @property {FormatsConfig} formats Date/time formats config. + * @property {L10nSettings} l10n Localization settings. + * @property {FormatsConfig} formats Date/time formats config. * @property {TimezoneConfig} timezone Timezone settings. */ @@ -373,10 +373,10 @@ const formatMap = { /** * Formats a date. Does not alter the date's timezone. * - * @param {string} dateFormat PHP-style formatting string. - * See php.net/date. + * @param {string} dateFormat PHP-style formatting string. + * See php.net/date. * @param {Moment | Date | string | undefined} dateValue Date object or string, - * parsable by moment.js. + * parsable by moment.js. * * @return {string} Formatted date. */ @@ -415,13 +415,13 @@ export function format( dateFormat, dateValue = new Date() ) { /** * Formats a date (like `date()` in PHP). * - * @param {string} dateFormat PHP-style formatting string. - * See php.net/date. + * @param {string} dateFormat PHP-style formatting string. + * See php.net/date. * @param {Moment | Date | string | undefined} dateValue Date object or string, parsable - * by moment.js. - * @param {string | undefined} timezone Timezone to output result in or a - * UTC offset. Defaults to timezone from - * site. + * by moment.js. + * @param {string | undefined} timezone Timezone to output result in or a + * UTC offset. Defaults to timezone from + * site. * * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones * @see https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC @@ -436,10 +436,10 @@ export function date( dateFormat, dateValue = new Date(), timezone ) { /** * Formats a date (like `date()` in PHP), in the UTC timezone. * - * @param {string} dateFormat PHP-style formatting string. - * See php.net/date. + * @param {string} dateFormat PHP-style formatting string. + * See php.net/date. * @param {Moment | Date | string | undefined} dateValue Date object or string, - * parsable by moment.js. + * parsable by moment.js. * * @return {string} Formatted date in English. */ @@ -454,15 +454,15 @@ export function gmdate( dateFormat, dateValue = new Date() ) { * Backward Compatibility Notice: if `timezone` is set to `true`, the function * behaves like `gmdateI18n`. * - * @param {string} dateFormat PHP-style formatting string. - * See php.net/date. - * @param {Moment | Date | string | undefined} dateValue Date object or string, parsable by - * moment.js. - * @param {string | boolean | undefined} timezone Timezone to output result in or a - * UTC offset. Defaults to timezone from - * site. Notice: `boolean` is effectively - * deprecated, but still supported for - * backward compatibility reasons. + * @param {string} dateFormat PHP-style formatting string. + * See php.net/date. + * @param {Moment | Date | string | undefined} dateValue Date object or string, parsable by + * moment.js. + * @param {string | boolean | undefined} timezone Timezone to output result in or a + * UTC offset. Defaults to timezone from + * site. Notice: `boolean` is effectively + * deprecated, but still supported for + * backward compatibility reasons. * * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones * @see https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC @@ -487,10 +487,10 @@ export function dateI18n( dateFormat, dateValue = new Date(), timezone ) { * Formats a date (like `wp_date()` in PHP), translating it into site's locale * and using the UTC timezone. * - * @param {string} dateFormat PHP-style formatting string. - * See php.net/date. + * @param {string} dateFormat PHP-style formatting string. + * See php.net/date. * @param {Moment | Date | string | undefined} dateValue Date object or string, - * parsable by moment.js. + * parsable by moment.js. * * @return {string} Formatted date. */ @@ -533,10 +533,10 @@ export function getDate( dateString ) { * Creates a moment instance using the given timezone or, if none is provided, using global settings. * * @param {Moment | Date | string | undefined} dateValue Date object or string, parsable - * by moment.js. - * @param {string | undefined} timezone Timezone to output result in or a - * UTC offset. Defaults to timezone from - * site. + * by moment.js. + * @param {string | undefined} timezone Timezone to output result in or a + * UTC offset. Defaults to timezone from + * site. * * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones * @see https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC diff --git a/packages/docgen/lib/engine.js b/packages/docgen/lib/engine.js index e06705a1f2564..952a07c4506c7 100644 --- a/packages/docgen/lib/engine.js +++ b/packages/docgen/lib/engine.js @@ -38,10 +38,10 @@ 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. + * Intermediate Representation from a path relative to the file + * being parsed. * * @return {Object} Intermediate Representation in JSON. */ diff --git a/packages/docgen/lib/get-intermediate-representation.js b/packages/docgen/lib/get-intermediate-representation.js index 4e1e3fe97e4c5..253283d74a27f 100644 --- a/packages/docgen/lib/get-intermediate-representation.js +++ b/packages/docgen/lib/get-intermediate-representation.js @@ -121,11 +121,11 @@ 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. + * and returns the intermediate representation of the dependency file. * * @return {Object} Intermediate Representation in JSON. */ diff --git a/packages/docgen/lib/get-type-annotation.js b/packages/docgen/lib/get-type-annotation.js index e3fc4a4f9529e..b74996239623c 100644 --- a/packages/docgen/lib/get-type-annotation.js +++ b/packages/docgen/lib/get-type-annotation.js @@ -8,12 +8,13 @@ const { types: babelTypes } = require( '@babel/core' ); /** @typedef {ReturnType<import('comment-parser').parse>[0]} CommentBlock */ /** @typedef {CommentBlock['tags'][0]} CommentTag */ /** @typedef {babelTypes.TSType} TypeAnnotation */ +/** @typedef {babelTypes.TSCallSignatureDeclaration | babelTypes.TSFunctionType | babelTypes.TSConstructSignatureDeclaration} ExtendedTypeAnnotation */ /** @typedef {import('@babel/core').Node} ASTNode */ /* eslint-enable jsdoc/valid-types */ /** - * @param {babelTypes.TSCallSignatureDeclaration | babelTypes.TSFunctionType | babelTypes.TSConstructSignatureDeclaration} typeAnnotation - * @param {' => ' | ': '} returnIndicator The return indicator to use. Allows using the same function for function annotations and object call properties. + * @param {ExtendedTypeAnnotation} typeAnnotation + * @param {' => ' | ': '} returnIndicator The return indicator to use. Allows using the same function for function annotations and object call properties. */ function getFunctionTypeAnnotation( typeAnnotation, returnIndicator ) { const nonRestParams = typeAnnotation.parameters @@ -447,9 +448,9 @@ function getQualifiedObjectPatternTypeAnnotation( tag, paramType ) { } /** - * @param {CommentTag} tag The documented parameter. - * @param {ASTNode} declarationToken The function the parameter is documented on. - * @param {number} paramIndex The parameter index. + * @param {CommentTag} tag The documented parameter. + * @param {ASTNode} declarationToken The function the parameter is documented on. + * @param {number} paramIndex The parameter index. * @return {null | string} The parameter's type annotation. */ function getParamTypeAnnotation( tag, declarationToken, paramIndex ) { @@ -546,8 +547,8 @@ function getVariableTypeAnnotation( declarationToken ) { module.exports = /** - * @param {CommentTag} tag A comment tag. - * @param {ASTNode} token A function token. + * @param {CommentTag} tag A comment tag. + * @param {ASTNode} token A function token. * @param {number | null} index The index of the parameter or `null` if not a param tag. * @return {null | string} The type annotation for the given tag or null if the tag has no type annotation. */ diff --git a/packages/docgen/lib/markdown/embed.js b/packages/docgen/lib/markdown/embed.js index aecd6b909ba4b..5b79c83932603 100644 --- a/packages/docgen/lib/markdown/embed.js +++ b/packages/docgen/lib/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/test/fixtures/tags-function/code.js b/packages/docgen/test/fixtures/tags-function/code.js index 4e0bd9644fb90..00b529b8691f3 100644 --- a/packages/docgen/test/fixtures/tags-function/code.js +++ b/packages/docgen/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/caret-range-from-point.js b/packages/dom/src/dom/caret-range-from-point.js index 3088e528c9981..fb32c15f0f975 100644 --- a/packages/dom/src/dom/caret-range-from-point.js +++ b/packages/dom/src/dom/caret-range-from-point.js @@ -4,9 +4,9 @@ * * @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 {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. * * @return {Range | null} The best range for the given point. */ diff --git a/packages/dom/src/dom/clean-node-list.js b/packages/dom/src/dom/clean-node-list.js index 0ac9f7dd62271..ac1f2d039958e 100644 --- a/packages/dom/src/dom/clean-node-list.js +++ b/packages/dom/src/dom/clean-node-list.js @@ -16,12 +16,12 @@ import isElement from './is-element'; /* eslint-disable jsdoc/valid-types */ /** * @typedef SchemaItem - * @property {string[]} [attributes] Attributes. - * @property {(string | RegExp)[]} [classes] Classnames or RegExp to test against. - * @property {'*' | { [tag: string]: SchemaItem }} [children] Child schemas. - * @property {string[]} [require] Selectors to test required children against. Leave empty or undefined if there are no requirements. - * @property {boolean} allowEmpty Whether to allow nodes without children. - * @property {(node: Node) => boolean} [isMatch] Function to test whether a node is a match. If left undefined any node will be assumed to match. + * @property {string[]} [attributes] Attributes. + * @property {(string | RegExp)[]} [classes] Classnames or RegExp to test against. + * @property {'*' | { [tag: string]: SchemaItem }} [children] Child schemas. + * @property {string[]} [require] Selectors to test required children against. Leave empty or undefined if there are no requirements. + * @property {boolean} allowEmpty Whether to allow nodes without children. + * @property {(node: Node) => boolean} [isMatch] Function to test whether a node is a match. If left undefined any node will be assumed to match. */ /** @typedef {{ [tag: string]: SchemaItem }} Schema */ diff --git a/packages/dom/src/dom/hidden-caret-range-from-point.js b/packages/dom/src/dom/hidden-caret-range-from-point.js index b0366e4becfe9..2b7afdfea4cdc 100644 --- a/packages/dom/src/dom/hidden-caret-range-from-point.js +++ b/packages/dom/src/dom/hidden-caret-range-from-point.js @@ -9,10 +9,10 @@ import getComputedStyle from './get-computed-style'; * Gives the container a temporary high z-index (above any UI). * 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 {HTMLElement} container Container in which the range is expected to be found. + * @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 {HTMLElement} container Container in which the range is expected to be found. * * @return {?Range} The best range for the given point. */ diff --git a/packages/dom/src/dom/is-edge.js b/packages/dom/src/dom/is-edge.js index d10f9a97263fb..b5dc5d301357f 100644 --- a/packages/dom/src/dom/is-edge.js +++ b/packages/dom/src/dom/is-edge.js @@ -14,8 +14,8 @@ import isInputOrTextArea from './is-input-or-text-area'; * horizontal position by default. Set `onlyVertical` to true to check only * vertically. * - * @param {Element} container Focusable element. - * @param {boolean} isReverse Set to true to check left, false to check right. + * @param {Element} container Focusable element. + * @param {boolean} isReverse Set to true to check left, false to check right. * @param {boolean} [onlyVertical=false] Set to true to check only vertical position. * * @return {boolean} True if at the edge, false if not. diff --git a/packages/dom/src/dom/place-caret-at-vertical-edge.js b/packages/dom/src/dom/place-caret-at-vertical-edge.js index d949a5d7da8df..6298eae652341 100644 --- a/packages/dom/src/dom/place-caret-at-vertical-edge.js +++ b/packages/dom/src/dom/place-caret-at-vertical-edge.js @@ -9,9 +9,9 @@ import { assertIsDefined } from '../utils/assert-is-defined'; * Places the caret at the top or bottom of a given element. * * @param {HTMLElement} container Focusable element. - * @param {boolean} isReverse True for bottom, false for top. - * @param {DOMRect} [rect] The rectangle to position the caret with. - * @param {boolean} [mayUseScroll=true] True to allow scrolling, false to disallow. + * @param {boolean} isReverse True for bottom, false for top. + * @param {DOMRect} [rect] The rectangle to position the caret with. + * @param {boolean} [mayUseScroll=true] True to allow scrolling, false to disallow. */ export default function placeCaretAtVerticalEdge( container, diff --git a/packages/dom/src/dom/remove-invalid-html.js b/packages/dom/src/dom/remove-invalid-html.js index f2ab3a14c59c1..51c676af74af1 100644 --- a/packages/dom/src/dom/remove-invalid-html.js +++ b/packages/dom/src/dom/remove-invalid-html.js @@ -6,9 +6,9 @@ import cleanNodeList from './clean-node-list'; /** * Given a schema, unwraps or removes nodes, attributes and classes on HTML. * - * @param {string} HTML The HTML to clean up. + * @param {string} HTML The HTML to clean up. * @param {import('./clean-node-list').Schema} schema Schema for the HTML. - * @param {boolean} inline Whether to clean for inline mode. + * @param {boolean} inline Whether to clean for inline mode. * * @return {string} The cleaned up HTML. */ diff --git a/packages/dom/src/dom/replace-tag.js b/packages/dom/src/dom/replace-tag.js index 9bb74e9a631d5..18a19c353431c 100644 --- a/packages/dom/src/dom/replace-tag.js +++ b/packages/dom/src/dom/replace-tag.js @@ -6,8 +6,8 @@ import { assertIsDefined } from '../utils/assert-is-defined'; /** * 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/dom/src/phrasing-content.js b/packages/dom/src/phrasing-content.js index cb8552914eb69..d233ef2eec8b4 100644 --- a/packages/dom/src/phrasing-content.js +++ b/packages/dom/src/phrasing-content.js @@ -15,8 +15,8 @@ import { omit, without } from 'lodash'; /** * @typedef SemanticElementDefinition - * @property {string[]} [attributes] Content attributes - * @property {ContentSchema} [children] Content attributes + * @property {string[]} [attributes] Content attributes + * @property {ContentSchema} [children] Content attributes */ /** @@ -142,7 +142,7 @@ const phrasingContentSchema = { * @see https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content * * @param {string} [context] Set to "paste" to exclude invisible elements and - * sensitive data. + * sensitive data. * * @return {Partial<ContentSchema>} Schema. */ 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/delete-theme.js b/packages/e2e-test-utils/src/delete-theme.js index 40885968af749..98b7e2b458923 100644 --- a/packages/e2e-test-utils/src/delete-theme.js +++ b/packages/e2e-test-utils/src/delete-theme.js @@ -11,9 +11,9 @@ import { isThemeInstalled } from './theme-installed'; /** * Deletes a theme from the site, activating another theme if necessary. * - * @param {string} slug Theme slug. - * @param {Object?} settings Optional settings object. - * @param {string?} settings.newThemeSlug A theme to switch to if the theme to delete is active. Required if the theme to delete is active. + * @param {string} slug Theme slug. + * @param {Object?} settings Optional settings object. + * @param {string?} settings.newThemeSlug A theme to switch to if the theme to delete is active. Required if the theme to delete is active. * @param {string?} settings.newThemeSearchTerm A search term to use if the new theme is not findable by its slug. */ export async function deleteTheme( 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/install-theme.js b/packages/e2e-test-utils/src/install-theme.js index 450ffd6aa9847..d030165c7cb97 100644 --- a/packages/e2e-test-utils/src/install-theme.js +++ b/packages/e2e-test-utils/src/install-theme.js @@ -9,8 +9,8 @@ import { isThemeInstalled } from './theme-installed'; /** * Installs a theme from the WP.org repository. * - * @param {string} slug Theme slug. - * @param {Object?} settings Optional settings object. + * @param {string} slug Theme slug. + * @param {Object?} settings Optional settings object. * @param {string?} settings.searchTerm Search term to use if the theme is not findable by its slug. */ export async function installTheme( 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/posts.js b/packages/e2e-test-utils/src/posts.js index c0730d90c62b0..722dd77f9939a 100644 --- a/packages/e2e-test-utils/src/posts.js +++ b/packages/e2e-test-utils/src/posts.js @@ -13,7 +13,7 @@ import { visitAdminPage } from './visit-admin-page'; /** * Navigates to the post listing screen and bulk-trashes any posts which exist. * - * @param {string} postType - String slug for type of post to trash. + * @param {string} postType - String slug for type of post to trash. * @param {string} postStatus - String status of posts to trash. * * @return {Promise} Promise resolving once posts have been trashed. 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 b79f27c1d4a72..a26a648aab9a0 100644 --- a/packages/e2e-test-utils/src/press-key-with-modifier.js +++ b/packages/e2e-test-utils/src/press-key-with-modifier.js @@ -137,7 +137,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/toggle-preferences-option.js b/packages/e2e-test-utils/src/toggle-preferences-option.js index 03472c1314391..fc644b6357916 100644 --- a/packages/e2e-test-utils/src/toggle-preferences-option.js +++ b/packages/e2e-test-utils/src/toggle-preferences-option.js @@ -7,8 +7,8 @@ import { clickOnMoreMenuItem } from './click-on-more-menu-item'; /** * Toggles a preference option with the given tab label and the option label. * - * @param {string} tabLabel The preferences tab label to click. - * @param {string} optionLabel The option label to search the button for. + * @param {string} tabLabel The preferences tab label to click. + * @param {string} optionLabel The option label to search the button for. * @param {boolean} [shouldBeChecked] If true, turns the option on. If false, off. If not provided, the option will be toggled. */ export async function togglePreferencesOption( diff --git a/packages/e2e-test-utils/src/visit-admin-page.js b/packages/e2e-test-utils/src/visit-admin-page.js index 5b9bbe043bc58..4382f14a3134b 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/fixtures/utils.js b/packages/e2e-tests/fixtures/utils.js index eb27ec4690d52..ab29623e58c7d 100644 --- a/packages/e2e-tests/fixtures/utils.js +++ b/packages/e2e-tests/fixtures/utils.js @@ -41,8 +41,9 @@ export function getAvailableBlockFixturesBasenames() { /** * Reads a block fixture file, trims the contents and returns an object containing filename and file (contents) properties. * - * @param {string} basename The filename of the fixture file without the file extension. - * @return {{filename: string, file: (string|null)}} An object containing the filename + extension, and the trimmed contents of that file. + * @param {string} basename The filename of the fixture file without the file extension. + * + * @return {{filename: string, file: (string|null)}} An object containing the filename + extension, and the trimmed contents of that file. */ export function getBlockFixtureHTML( basename ) { const filename = `${ basename }.html`; diff --git a/packages/e2e-tests/specs/editor/plugins/annotations.test.js b/packages/e2e-tests/specs/editor/plugins/annotations.test.js index 31a3a73893015..8de8ea026bca3 100644 --- a/packages/e2e-tests/specs/editor/plugins/annotations.test.js +++ b/packages/e2e-tests/specs/editor/plugins/annotations.test.js @@ -34,7 +34,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/blocks/navigation.test.js b/packages/e2e-tests/specs/experiments/blocks/navigation.test.js index c29e1f5dadb78..b984a46bda3d3 100644 --- a/packages/e2e-tests/specs/experiments/blocks/navigation.test.js +++ b/packages/e2e-tests/specs/experiments/blocks/navigation.test.js @@ -56,7 +56,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 ) ); @@ -107,7 +107,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( @@ -174,10 +174,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/e2e-tests/specs/experiments/navigation-editor.test.js b/packages/e2e-tests/specs/experiments/navigation-editor.test.js index 15e8b02c3492b..301bbae01c705 100644 --- a/packages/e2e-tests/specs/experiments/navigation-editor.test.js +++ b/packages/e2e-tests/specs/experiments/navigation-editor.test.js @@ -93,7 +93,7 @@ const REST_PAGES_ROUTES = [ * routes (expressed 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 ) ); diff --git a/packages/edit-navigation/src/store/controls.js b/packages/edit-navigation/src/store/controls.js index ba2121d9a8824..888efd8127a53 100644 --- a/packages/edit-navigation/src/store/controls.js +++ b/packages/edit-navigation/src/store/controls.js @@ -97,7 +97,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 ) { @@ -114,7 +114,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/menu-items-to-blocks.js b/packages/edit-navigation/src/store/menu-items-to-blocks.js index 21bfd97529925..024c267d67cef 100644 --- a/packages/edit-navigation/src/store/menu-items-to-blocks.js +++ b/packages/edit-navigation/src/store/menu-items-to-blocks.js @@ -93,16 +93,16 @@ function mapMenuItemsToBlocks( menuItems ) { * * @typedef WPNavMenuItem * - * @property {Object} title stores the raw and rendered versions of the title/label for this menu item. - * @property {Array} xfn the XFN relationships expressed in the link of this menu item. - * @property {Array} classes the HTML class attributes for this menu item. - * @property {string} attr_title the HTML title attribute for this menu item. - * @property {string} object The type of object originally represented, such as 'category', 'post', or 'attachment'. - * @property {string} object_id The DB ID of the original object this menu item represents, e.g. ID for posts and term_id for categories. + * @property {Object} title stores the raw and rendered versions of the title/label for this menu item. + * @property {Array} xfn the XFN relationships expressed in the link of this menu item. + * @property {Array} classes the HTML class attributes for this menu item. + * @property {string} attr_title the HTML title attribute for this menu item. + * @property {string} object The type of object originally represented, such as 'category', 'post', or 'attachment'. + * @property {string} object_id The DB ID of the original object this menu item represents, e.g. ID for posts and term_id for categories. * @property {string} description The description of this menu item. - * @property {string} url The URL to which this menu item points. - * @property {string} type The family of objects originally represented, such as 'post_type' or 'taxonomy'. - * @property {string} target The target attribute of the link element for this menu item. + * @property {string} url The URL to which this menu item points. + * @property {string} type The family of objects originally represented, such as 'post_type' or 'taxonomy'. + * @property {string} target The target attribute of the link element for this menu item. */ /** @@ -175,9 +175,9 @@ function menuItemToBlockAttributes( { * * 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/edit-navigation/src/store/reducer.js b/packages/edit-navigation/src/store/reducer.js index cab46d584cf85..ba95ce158d33c 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 ed9b947f62b49..f3dcad8473de7 100644 --- a/packages/edit-navigation/src/store/selectors.js +++ b/packages/edit-navigation/src/store/selectors.js @@ -73,8 +73,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-navigation/src/store/utils.js b/packages/edit-navigation/src/store/utils.js index ffa71c376e29c..13da7255ad626 100644 --- a/packages/edit-navigation/src/store/utils.js +++ b/packages/edit-navigation/src/store/utils.js @@ -28,16 +28,16 @@ import { NEW_TAB_TARGET_ATTRIBUTE } from '../constants'; * * @typedef WPNavMenuItem * - * @property {Object} title stores the raw and rendered versions of the title/label for this menu item. - * @property {Array} xfn the XFN relationships expressed in the link of this menu item. - * @property {Array} classes the HTML class attributes for this menu item. - * @property {string} attr_title the HTML title attribute for this menu item. - * @property {string} object The type of object originally represented, such as 'category', 'post', or 'attachment'. - * @property {string} object_id The DB ID of the original object this menu item represents, e.g. ID for posts and term_id for categories. + * @property {Object} title stores the raw and rendered versions of the title/label for this menu item. + * @property {Array} xfn the XFN relationships expressed in the link of this menu item. + * @property {Array} classes the HTML class attributes for this menu item. + * @property {string} attr_title the HTML title attribute for this menu item. + * @property {string} object The type of object originally represented, such as 'category', 'post', or 'attachment'. + * @property {string} object_id The DB ID of the original object this menu item represents, e.g. ID for posts and term_id for categories. * @property {string} description The description of this menu item. - * @property {string} url The URL to which this menu item points. - * @property {string} type The family of objects originally represented, such as 'post_type' or 'taxonomy'. - * @property {string} target The target attribute of the link element for this menu item. + * @property {string} url The URL to which this menu item points. + * @property {string} type The family of objects originally represented, such as 'post_type' or 'taxonomy'. + * @property {string} target The target attribute of the link element for this menu item. */ /** @@ -189,16 +189,16 @@ export function computeCustomizedAttribute( * * See: https://core.trac.wordpress.org/browser/tags/5.7.1/src/wp-includes/nav-menu.php#L438. * - * @param {Object} blockAttributes the block attributes of the block to be converted into menu item fields. - * @param {string} blockAttributes.label the visual name of the block shown in the UI. - * @param {string} blockAttributes.url the URL for the link. - * @param {string} blockAttributes.description a link description. - * @param {string} blockAttributes.rel the XFN relationship expressed in the link of this menu item. - * @param {string} blockAttributes.className the custom CSS classname attributes for this block. - * @param {string} blockAttributes.title the HTML title attribute for the block's link. - * @param {string} blockAttributes.type the type of variation of the block used (eg: 'Post', 'Custom', 'Category'...etc). - * @param {number} blockAttributes.id the ID of the entity optionally associated with the block's link (eg: the Post ID). - * @param {string} blockAttributes.kind the family of objects originally represented, such as 'post-type' or 'taxonomy'. + * @param {Object} blockAttributes the block attributes of the block to be converted into menu item fields. + * @param {string} blockAttributes.label the visual name of the block shown in the UI. + * @param {string} blockAttributes.url the URL for the link. + * @param {string} blockAttributes.description a link description. + * @param {string} blockAttributes.rel the XFN relationship expressed in the link of this menu item. + * @param {string} blockAttributes.className the custom CSS classname attributes for this block. + * @param {string} blockAttributes.title the HTML title attribute for the block's link. + * @param {string} blockAttributes.type the type of variation of the block used (eg: 'Post', 'Custom', 'Category'...etc). + * @param {number} blockAttributes.id the ID of the entity optionally associated with the block's link (eg: the Post ID). + * @param {string} blockAttributes.kind the family of objects originally represented, such as 'post-type' or 'taxonomy'. * @param {boolean} blockAttributes.opensInNewTab whether or not the block's link should open in a new tab. * @return {Object} the menu item (converted from block attributes). */ 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 6005fe7bab85f..77024f45a5c93 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 @@ -21,7 +21,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 689a088a06833..798753cfea357 100644 --- a/packages/edit-post/src/components/browser-url/index.js +++ b/packages/edit-post/src/components/browser-url/index.js @@ -20,7 +20,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. @@ -65,8 +65,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 b9b204ec8e829..a729e344246ca 100644 --- a/packages/edit-post/src/components/editor-initialization/listener-hooks.js +++ b/packages/edit-post/src/components/editor-initialization/listener-hooks.js @@ -19,7 +19,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..64bdc2f1b1b73 100644 --- a/packages/edit-post/src/components/editor-initialization/utils.js +++ b/packages/edit-post/src/components/editor-initialization/utils.js @@ -2,11 +2,12 @@ * 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 - * initial call. - * @return {Function} Listener creator. + * @param {Function} selector Selector. + * @param {Function} listener Listener. + * @param {boolean} initial Flags whether listener should be invoked on + * initial call. + * + * @return {Function} Listener creator. */ export const onChangeListener = ( selector, listener, initial = false ) => { let previousValue = selector(); 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 ab6957931e458..0e02afa061c11 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 * ```js 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 e0bb805b403f8..1bb1a5e43153e 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 e3f768798cb2e..3c6b5aeb097e0 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 @@ -55,10 +55,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 ee05ff954e5e3..aa697e32cf96e 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,10 +29,10 @@ 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 {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 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 4d4dff91e3791..5dc16bad39ff7 100644 --- a/packages/edit-post/src/components/sidebar/plugin-sidebar/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-sidebar/index.js @@ -23,11 +23,11 @@ import { store as editPostStore } from '../../../store'; * * @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 the toolbar. When set to `true` it also automatically renders a corresponding menu item. + * @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 the toolbar. When set to `true` it also automatically renders a corresponding menu item. * @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/index.native.js b/packages/edit-post/src/index.native.js index ff3a028bf719c..60548d4cdf4c3 100644 --- a/packages/edit-post/src/index.native.js +++ b/packages/edit-post/src/index.native.js @@ -17,9 +17,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/reducer.js b/packages/edit-post/src/store/reducer.js index c12d54ec97298..e11d357790195 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. */ @@ -244,7 +244,7 @@ export function deviceType( state = 'Desktop', action ) { * Note: this reducer interacts with the list view panel reducer * to make sure that only one of the two panels is open at the same time. * - * @param {Object} state Current state. + * @param {Object} state Current state. * @param {Object} action Dispatched action. */ export function blockInserterPanel( state = false, action ) { @@ -263,7 +263,7 @@ export function blockInserterPanel( state = false, action ) { * Note: this reducer interacts with the inserter panel reducer * to make sure that only one of the two panels is open at the same time. * - * @param {Object} state Current state. + * @param {Object} state Current state. * @param {Object} action Dispatched action. */ export function listViewPanel( state = false, action ) { diff --git a/packages/edit-post/src/store/selectors.js b/packages/edit-post/src/store/selectors.js index ad35000899324..bc8fac5e4b243 100644 --- a/packages/edit-post/src/store/selectors.js +++ b/packages/edit-post/src/store/selectors.js @@ -44,8 +44,9 @@ export const isEditorSidebarOpened = createRegistrySelector( /** * Returns true if the plugin sidebar is opened. * - * @param {Object} state Global application state - * @return {boolean} Whether the plugin sidebar is opened. + * @param {Object} state Global application state. + * + * @return {boolean} Whether the plugin sidebar is opened. */ export const isPluginSidebarOpened = createRegistrySelector( ( select ) => () => { @@ -155,8 +156,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. */ @@ -171,8 +172,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. */ @@ -196,8 +197,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. */ @@ -286,7 +287,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. */ @@ -297,7 +298,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. */ @@ -319,7 +320,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. */ @@ -342,7 +343,7 @@ export function __experimentalGetInsertionPoint( state ) { /** * Returns true if the list view is opened. * - * @param {Object} state Global application state. + * @param {Object} state Global application state. * * @return {boolean} Whether the list view is opened. */ @@ -353,7 +354,7 @@ export function isListViewOpened( state ) { /** * Returns true if the template editing mode is enabled. * - * @param {Object} state Global application state. + * @param {Object} state Global application state. * * @return {boolean} Whether we're editing the template. */ diff --git a/packages/edit-post/src/utils/meta-boxes.js b/packages/edit-post/src/utils/meta-boxes.js index a781b96318402..c931568f0bc48 100644 --- a/packages/edit-post/src/utils/meta-boxes.js +++ b/packages/edit-post/src/utils/meta-boxes.js @@ -3,8 +3,9 @@ * 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. - * @return {string} HTML content. + * @param {string} location Meta Box location. + * + * @return {string} HTML content. */ export const getMetaBoxContainer = ( location ) => { const area = document.querySelector( 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 45241512c0e7d..54949b07bf198 100644 --- a/packages/edit-site/src/components/editor/global-styles-renderer.js +++ b/packages/edit-site/src/components/editor/global-styles-renderer.js @@ -120,7 +120,7 @@ function flattenTree( input = {}, prefix, token ) { /** * Transform given style tree into a set of style declarations. * - * @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 1cbdb9bd19e95..5c1ea92a4df4d 100644 --- a/packages/edit-site/src/store/actions.js +++ b/packages/edit-site/src/store/actions.js @@ -46,7 +46,7 @@ export function __experimentalSetPreviewDeviceType( deviceType ) { /** * Returns an action object used to set a template. * - * @param {number} templateId The template ID. + * @param {number} templateId The template ID. * @param {string} templateSlug The template slug. * @return {Object} Action object. */ @@ -149,11 +149,11 @@ export function setHomeTemplateId( homeTemplateId ) { * Resolves the template for a page and displays both. If no path is given, attempts * to use the postId to generate a path like `?p=${ postId }`. * - * @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 01423f4f082d2..505b06605cbf9 100644 --- a/packages/edit-site/src/store/reducer.js +++ b/packages/edit-site/src/store/reducer.js @@ -12,8 +12,8 @@ import { MENU_ROOT } from '../components/navigation-sidebar/navigation-panel/con /** * 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 {Object} Updated state. */ export const preferences = combineReducers( { @@ -99,7 +99,7 @@ export function editedPost( 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. @@ -120,7 +120,7 @@ export function homeTemplateId( state, action ) { * Note: this reducer interacts with the inserter and list view panels reducers * to make sure that only one of the three panels is open at the same time. * - * @param {Object} state Current state. + * @param {Object} state Current state. * @param {Object} action Dispatched action. */ export function navigationPanel( @@ -189,7 +189,7 @@ export function blockInserterPanel( state = false, action ) { * Note: this reducer interacts with the navigation and inserter panels reducers * to make sure that only one of the three panels is open at the same time. * - * @param {Object} state Current state. + * @param {Object} state Current state. * @param {Object} action Dispatched action. */ export function listViewPanel( state = false, action ) { diff --git a/packages/edit-widgets/src/store/actions.js b/packages/edit-widgets/src/store/actions.js index 7ae0bb06d6532..c14a30259556f 100644 --- a/packages/edit-widgets/src/store/actions.js +++ b/packages/edit-widgets/src/store/actions.js @@ -25,8 +25,8 @@ import { STORE_NAME as editWidgetsStoreName } from './constants'; * Persists a stub post with given ID to core data store. The post is meant to be in-memory only and * shouldn't be saved via the API. * - * @param {string} id Post ID. - * @param {Array} blocks Blocks the post should consist of. + * @param {string} id Post ID. + * @param {Array} blocks Blocks the post should consist of. * @return {Object} The post object. */ export const persistStubPost = function* ( id, blocks ) { @@ -288,9 +288,10 @@ function* trySaveWidgetArea( widgetAreaId ) { /** * Sets the clientId stored for a particular widgetId. * - * @param {number} clientId Client id. - * @param {number} widgetId Widget id. - * @return {Object} Action. + * @param {number} clientId Client id. + * @param {number} widgetId Widget id. + * + * @return {Object} Action. */ export function setWidgetIdForClientId( clientId, widgetId ) { return { @@ -303,8 +304,9 @@ export function setWidgetIdForClientId( clientId, widgetId ) { /** * Sets the open state of all the widget areas. * - * @param {Object} widgetAreasOpenState The open states of all the widget areas. - * @return {Object} Action. + * @param {Object} widgetAreasOpenState The open states of all the widget areas. + * + * @return {Object} Action. */ export function setWidgetAreasOpenState( widgetAreasOpenState ) { return { @@ -316,9 +318,10 @@ export function setWidgetAreasOpenState( widgetAreasOpenState ) { /** * Sets the open state of the widget area. * - * @param {string} clientId The clientId of the widget area. - * @param {boolean} isOpen Whether the widget area should be opened. - * @return {Object} Action. + * @param {string} clientId The clientId of the widget area. + * @param {boolean} isOpen Whether the widget area should be opened. + * + * @return {Object} Action. */ export function setIsWidgetAreaOpen( clientId, isOpen ) { return { diff --git a/packages/edit-widgets/src/store/controls.js b/packages/edit-widgets/src/store/controls.js index 0694ac9733ccd..9565a25277254 100644 --- a/packages/edit-widgets/src/store/controls.js +++ b/packages/edit-widgets/src/store/controls.js @@ -101,7 +101,7 @@ export function resolveWidgets( query = buildWidgetsQuery() ) { * * @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 ) { @@ -118,7 +118,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 7494bd5b49724..e762f285b35e7 100644 --- a/packages/edit-widgets/src/store/reducer.js +++ b/packages/edit-widgets/src/store/reducer.js @@ -28,9 +28,10 @@ const createWithInitialState = ( initialState ) => ( reducer ) => { /** * Controls the open state of the widget areas. * - * @param {Object} state Redux state - * @param {Object} action Redux action - * @return {Array} Updated state + * @param {Object} state Redux state. + * @param {Object} action Redux action. + * + * @return {Array} Updated state. */ export function widgetAreasOpenState( state = {}, action ) { const { type } = action; @@ -68,8 +69,8 @@ function blockInserterPanel( state = false, 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 {Object} Updated state. */ diff --git a/packages/edit-widgets/src/store/selectors.js b/packages/edit-widgets/src/store/selectors.js index f09c2e1fd30c1..70d315cac456c 100644 --- a/packages/edit-widgets/src/store/selectors.js +++ b/packages/edit-widgets/src/store/selectors.js @@ -37,8 +37,9 @@ export const getWidgets = createRegistrySelector( ( select ) => () => { /** * Returns API widget data for a particular widget ID. * - * @param {number} id Widget ID - * @return {Object} API widget data for a particular widget ID. + * @param {number} id Widget ID. + * + * @return {Object} API widget data for a particular widget ID. */ export const getWidget = createRegistrySelector( ( select ) => ( state, id ) => { @@ -111,7 +112,7 @@ export const getEditedWidgetAreas = createRegistrySelector( /** * Returns all blocks representing reference widgets. * - * @param {string} referenceWidgetName Optional. If given, only reference widgets with this name will be returned. + * @param {string} referenceWidgetName Optional. If given, only reference widgets with this name will be returned. * @return {Array} List of all blocks representing reference widgets */ export const getReferenceWidgetBlocks = createRegistrySelector( @@ -181,7 +182,8 @@ export const isSavingWidgetAreas = createRegistrySelector( ( select ) => () => { * * @param {Array} state The open state of the widget areas. * @param {string} clientId The clientId of the widget area. - * @return {boolean} True if the widget area is open. + * + * @return {boolean} True if the widget area is open. */ export const getIsWidgetAreaOpen = ( state, clientId ) => { const { widgetAreasOpenState } = state; @@ -191,7 +193,7 @@ export const getIsWidgetAreaOpen = ( state, clientId ) => { /** * 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. */ @@ -202,7 +204,7 @@ export function isInserterOpened( state ) { /** * Returns true if a block can be inserted into a widget area. * - * @param {Array} state The open state of the widget areas. + * @param {Array} state The open state of the widget areas. * @param {string} blockName The name of the block being inserted. * * @return {boolean} True if the block can be inserted in a widget area. diff --git a/packages/edit-widgets/src/store/utils.js b/packages/edit-widgets/src/store/utils.js index ca2ed2eb3603d..5dc51cacb0460 100644 --- a/packages/edit-widgets/src/store/utils.js +++ b/packages/edit-widgets/src/store/utils.js @@ -62,8 +62,8 @@ export function buildWidgetsQuery() { * Creates a stub post with given id and set of blocks. Used as a governing entity records * for all widget areas. * - * @param {string} id Post ID. - * @param {Array} blocks The list of blocks. + * @param {string} id Post ID. + * @param {Array} blocks The list of blocks. * @return {Object} A stub post object formatted in compliance with the data layer. */ export const createStubPost = ( id, blocks ) => ( { diff --git a/packages/editor/src/components/post-publish-panel/postpublish.js b/packages/editor/src/components/post-publish-panel/postpublish.js index f7a7e5cfec245..b7d7179d024bc 100644 --- a/packages/editor/src/components/post-publish-panel/postpublish.js +++ b/packages/editor/src/components/post-publish-panel/postpublish.js @@ -26,7 +26,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 0868441d19406..a6e2bca9e5bbb 100644 --- a/packages/editor/src/components/post-saved-state/index.js +++ b/packages/editor/src/components/post-saved-state/index.js @@ -27,11 +27,11 @@ import { store as editorStore } from '../../store'; * 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 - * as dirty. - * @param {?boolean} props.forceIsSaving Whether to force the post to be marked - * as being saved. + * @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 + * as being saved. * @param {?boolean} props.showIconLabels Whether interface buttons show labels instead of icons * @return {import('@wordpress/element').WPComponent} The component. */ 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 46419366cd19b..5c4af91c4530a 100644 --- a/packages/editor/src/components/post-type-support-check/index.js +++ b/packages/editor/src/components/post-type-support-check/index.js @@ -18,12 +18,12 @@ import { store as editorStore } from '../../store'; * 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 - * type supports. - * @param {(string|string[])} props.supportKeys String or string array of keys - * to test. + * @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 + * to test. * * @return {WPComponent} The component to be rendered. */ diff --git a/packages/editor/src/store/actions.js b/packages/editor/src/store/actions.js index dcd47548b09d4..29f1c11fb0c45 100644 --- a/packages/editor/src/store/actions.js +++ b/packages/editor/src/store/actions.js @@ -32,9 +32,9 @@ import { * 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 @@ -180,7 +180,7 @@ export function updatePost() { * 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. */ @@ -447,7 +447,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. */ @@ -485,7 +485,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 * ``` @@ -535,7 +535,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 * ``` @@ -555,7 +555,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 * ``` @@ -575,7 +575,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 17583b3cf5b8c..c41aac33373aa 100644 --- a/packages/editor/src/store/controls.js +++ b/packages/editor/src/store/controls.js @@ -7,9 +7,10 @@ * * @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. - * @return {string} sessionStorage key + * @param {string} postId Post ID. + * @param {boolean} isPostNew Whether post new. + * + * @return {string} sessionStorage key */ function postKey( postId, isPostNew ) { return `wp-autosave-block-editor-post-${ diff --git a/packages/editor/src/store/reducer.js b/packages/editor/src/store/reducer.js index 07b2a74376a25..6172dac9eb651 100644 --- a/packages/editor/src/store/reducer.js +++ b/packages/editor/src/store/reducer.js @@ -124,8 +124,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. */ @@ -174,7 +174,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. @@ -184,7 +184,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. */ @@ -245,7 +245,7 @@ export function postAutosavingLock( state = {}, action ) { * 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 d9b3fbcd67888..b3d7e8e435b5a 100644 --- a/packages/editor/src/store/reducer.native.js +++ b/packages/editor/src/store/reducer.native.js @@ -27,8 +27,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. */ @@ -46,8 +46,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. */ @@ -63,8 +63,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/store/selectors.js b/packages/editor/src/store/selectors.js index 5f8a5492f86e2..871714e3bcedd 100644 --- a/packages/editor/src/store/selectors.js +++ b/packages/editor/src/store/selectors.js @@ -1703,7 +1703,7 @@ export const __experimentalGetDefaultTemplatePartAreas = createSelector( * Returns a default template type searched by slug. * * @param {Object} state Global application state. - * @param {string} slug The template type slug. + * @param {string} slug The template type slug. * * @return {Object} The template type. */ @@ -1717,7 +1717,7 @@ export const __experimentalGetDefaultTemplateType = createSelector( * Given a template entity, return information about it which is ready to be * rendered, such as the title, description, and icon. * - * @param {Object} state Global application state. + * @param {Object} state Global application state. * @param {Object} template The template for which we need information. * @return {Object} Information about the template, including title, description, and icon. */ diff --git a/packages/editor/src/utils/media-upload/index.js b/packages/editor/src/utils/media-upload/index.js index 416abfaee861b..f02e7ef80312b 100644 --- a/packages/editor/src/utils/media-upload/index.js +++ b/packages/editor/src/utils/media-upload/index.js @@ -18,13 +18,13 @@ import { store as editorStore } from '../../store'; * 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 75c37b2714efa..8aeb079d1a5a0 100644 --- a/packages/editor/src/utils/terms.js +++ b/packages/editor/src/utils/terms.js @@ -6,7 +6,7 @@ import { groupBy, map, unescape as lodashUnescapeString } 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 8eb6d73cbd2e3..c80a780ad2a76 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 - * appears. - * @property {number} tokenLength Length of string marking start of parent - * element. - * @property {number} [prevOffset] Running offset at which parsing should - * continue. - * @property {number} [leadingTextStart] Offset at which last closing element - * finished, used for finding text between - * elements. - * @property {WPElement[]} children Children. + * @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 + * element. + * @property {number} [prevOffset] Running offset at which parsing should + * continue. + * @property {number} [leadingTextStart] Offset at which last closing element + * finished, used for finding text between + * elements. + * @property {WPElement[]} children Children. */ /** @@ -101,9 +101,9 @@ function createFrame( * } * ``` * - * @param {string} interpolatedString The interpolation string to be parsed. - * @param {Object} conversionMap The map used to convert the string to - * a react element. + * @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,8 +293,8 @@ function addText() { * * @private * - * @param {Frame} frame The Frame containing the child element and it's - * token information. + * @param {Frame} frame The Frame containing the child element and it's + * token information. */ function addChild( frame ) { const { element, tokenStart, tokenLength, prevOffset, children } = frame; diff --git a/packages/element/src/react-platform.js b/packages/element/src/react-platform.js index fe3d3e94a9994..4c29f7da795dd 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, - * string, or fragment. - * @param {HTMLElement} container DOM node into which element should be rendered. + * @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. */ 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 9572e54b47a8b..fe8bf1e308379 100644 --- a/packages/env/lib/build-docker-compose-config.js +++ b/packages/env/lib/build-docker-compose-config.js @@ -19,9 +19,9 @@ const { dbEnv } = require( './config' ); /** * 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 - * source code (such as tests-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/parse-config.js b/packages/env/lib/config/parse-config.js index a0877fcb05945..ce0b7e044e070 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. @@ -61,9 +61,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. */ @@ -142,8 +142,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 c3aa849e6322d..aa0572306569f 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/init-config.js b/packages/env/lib/init-config.js index 75175853704a6..28a17947b2ee4 100644 --- a/packages/env/lib/init-config.js +++ b/packages/env/lib/init-config.js @@ -102,8 +102,9 @@ module.exports = async function initConfig( { * Generates the Dockerfile used by wp-env's development instance. * * @param {string} image The base docker image to use. - * @param {WPConfig} config The configuration object - * @return {string} The dockerfile contents. + * @param {WPConfig} config The configuration object. + * + * @return {string} The dockerfile contents. */ function dockerFileContents( image, config ) { let shouldInstallXdebug = true; 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 0cbd70c4ab22b..609e2b7040960 100644 --- a/packages/env/lib/wordpress.js +++ b/packages/env/lib/wordpress.js @@ -39,7 +39,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`; @@ -206,7 +206,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/CHANGELOG.md b/packages/eslint-plugin/CHANGELOG.md index 02ec24b6f2a0e..83e5fa595a985 100644 --- a/packages/eslint-plugin/CHANGELOG.md +++ b/packages/eslint-plugin/CHANGELOG.md @@ -2,6 +2,10 @@ ## Unreleased +### Enhancement + +- Adds JSDoc alignment check ([#25300](https://github.com/WordPress/gutenberg/pull/25300)). + ## 9.0.1 (2021-03-19) ### Bug Fix diff --git a/packages/eslint-plugin/configs/jsdoc.js b/packages/eslint-plugin/configs/jsdoc.js index afd8a585b27dd..b8f658433aad2 100644 --- a/packages/eslint-plugin/configs/jsdoc.js +++ b/packages/eslint-plugin/configs/jsdoc.js @@ -104,8 +104,17 @@ module.exports = { 'jsdoc/require-jsdoc': 'off', 'jsdoc/require-param-description': 'off', 'jsdoc/require-returns': 'off', + 'jsdoc/require-yields': 'off', 'jsdoc/check-access': 'error', 'jsdoc/check-alignment': 'error', + 'jsdoc/check-line-alignment': [ + 'warn', + 'always', + { + tags: [ 'param', 'arg', 'argument', 'property', 'prop' ], + preserveMainDescriptionPostDelimiter: true, + }, + ], 'jsdoc/check-param-names': 'error', 'jsdoc/check-property-names': 'error', 'jsdoc/check-tag-names': 'error', diff --git a/packages/eslint-plugin/package.json b/packages/eslint-plugin/package.json index 938ea7f179039..2f153c869c3e6 100644 --- a/packages/eslint-plugin/package.json +++ b/packages/eslint-plugin/package.json @@ -39,7 +39,7 @@ "eslint-config-prettier": "^7.1.0", "eslint-plugin-import": "^2.22.1", "eslint-plugin-jest": "^24.1.3", - "eslint-plugin-jsdoc": "^30.7.13", + "eslint-plugin-jsdoc": "^34.1.0", "eslint-plugin-jsx-a11y": "^6.4.1", "eslint-plugin-prettier": "^3.3.0", "eslint-plugin-react": "^7.22.0", diff --git a/packages/eslint-plugin/rules/i18n-text-domain.js b/packages/eslint-plugin/rules/i18n-text-domain.js index 22abec09dc290..a5b4797c4e7ba 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/rules/no-unsafe-wp-apis.js b/packages/eslint-plugin/rules/no-unsafe-wp-apis.js index 65bcc2170d45b..ceacc3dd38f59 100644 --- a/packages/eslint-plugin/rules/no-unsafe-wp-apis.js +++ b/packages/eslint-plugin/rules/no-unsafe-wp-apis.js @@ -34,8 +34,8 @@ module.exports = { }; /** - * @param {Object} _ - * @param {AllowedImportsMap} _.allowedImports + * @param {Object} _ + * @param {AllowedImportsMap} _.allowedImports * @param {import('eslint').Rule.RuleContext} _.context * * @return {(node: Node) => void} Listener function 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 54af960956d43..1fcfcfab1a7d2 100644 --- a/packages/hooks/src/createAddHook.js +++ b/packages/hooks/src/createAddHook.js @@ -9,17 +9,17 @@ import validateHookName from './validateHookName.js'; * * Adds the hook to the appropriate hooks container. * - * @param {string} hookName Name of hook to add - * @param {string} namespace The unique namespace identifying the callback in the form `vendor/plugin/function`. - * @param {import('.').Callback} callback Function to call when the hook is run - * @param {number} [priority=10] Priority of this hook + * @param {string} hookName Name of hook to add + * @param {string} namespace The unique namespace identifying the callback in the form `vendor/plugin/function`. + * @param {import('.').Callback} callback Function to call when the hook is run + * @param {number} [priority=10] Priority of this hook */ /** * Returns a function which, when invoked, will add a hook. * - * @param {import('.').Hooks} hooks Hooks instance. - * @param {import('.').StoreKey} storeKey + * @param {import('.').Hooks} hooks Hooks instance. + * @param {import('.').StoreKey} storeKey * * @return {AddHook} Function that adds a new hook. */ diff --git a/packages/hooks/src/createCurrentHook.js b/packages/hooks/src/createCurrentHook.js index a5565dc98e2cd..634901fe55f63 100644 --- a/packages/hooks/src/createCurrentHook.js +++ b/packages/hooks/src/createCurrentHook.js @@ -3,8 +3,8 @@ * currently running hook, or `null` if no hook of the given type is currently * running. * - * @param {import('.').Hooks} hooks Hooks instance. - * @param {import('.').StoreKey} storeKey + * @param {import('.').Hooks} hooks Hooks instance. + * @param {import('.').StoreKey} storeKey * * @return {() => string | null} Function that returns the current hook name or null. */ diff --git a/packages/hooks/src/createDidHook.js b/packages/hooks/src/createDidHook.js index c52aafbe65635..882ced1760c13 100644 --- a/packages/hooks/src/createDidHook.js +++ b/packages/hooks/src/createDidHook.js @@ -8,7 +8,7 @@ import validateHookName from './validateHookName.js'; * * 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 | undefined} The number of times the hook has run. */ @@ -17,8 +17,8 @@ import validateHookName from './validateHookName.js'; * Returns a function which, when invoked, will return the number of times a * hook has been called. * - * @param {import('.').Hooks} hooks Hooks instance. - * @param {import('.').StoreKey} storeKey + * @param {import('.').Hooks} hooks Hooks instance. + * @param {import('.').StoreKey} storeKey * * @return {DidHook} Function that returns a hook's call count. */ diff --git a/packages/hooks/src/createDoingHook.js b/packages/hooks/src/createDoingHook.js index 52afbce3ba497..652ab06b4ba72 100644 --- a/packages/hooks/src/createDoingHook.js +++ b/packages/hooks/src/createDoingHook.js @@ -2,8 +2,8 @@ * @callback DoingHook * Returns whether a hook is currently being executed. * - * @param {string} [hookName] The name of the hook to check for. If - * omitted, will check for any hook being executed. + * @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. */ @@ -12,8 +12,8 @@ * Returns a function which, when invoked, will return whether a hook is * currently being executed. * - * @param {import('.').Hooks} hooks Hooks instance. - * @param {import('.').StoreKey} storeKey + * @param {import('.').Hooks} hooks Hooks instance. + * @param {import('.').StoreKey} storeKey * * @return {DoingHook} Function that returns whether a hook is currently * being executed. diff --git a/packages/hooks/src/createHasHook.js b/packages/hooks/src/createHasHook.js index 36a8c0450626e..5ed82127f2cc7 100644 --- a/packages/hooks/src/createHasHook.js +++ b/packages/hooks/src/createHasHook.js @@ -13,8 +13,8 @@ * Returns a function which, when invoked, will return whether any handlers are * attached to a particular hook. * - * @param {import('.').Hooks} hooks Hooks instance. - * @param {import('.').StoreKey} storeKey + * @param {import('.').Hooks} hooks Hooks instance. + * @param {import('.').StoreKey} storeKey * * @return {HasHook} 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 0b649310f1d59..39b87eb704cd3 100644 --- a/packages/hooks/src/createRemoveHook.js +++ b/packages/hooks/src/createRemoveHook.js @@ -20,11 +20,11 @@ import validateHookName from './validateHookName.js'; * Returns a function which, when invoked, will remove a specified hook or all * hooks by the given name. * - * @param {import('.').Hooks} hooks Hooks instance. - * @param {import('.').StoreKey} storeKey - * @param {boolean} [removeAll=false] Whether to remove all callbacks for a hookName, - * without regard to namespace. Used to create - * `removeAll*` functions. + * @param {import('.').Hooks} hooks Hooks instance. + * @param {import('.').StoreKey} storeKey + * @param {boolean} [removeAll=false] Whether to remove all callbacks for a hookName, + * without regard to namespace. Used to create + * `removeAll*` functions. * * @return {RemoveHook} Function that removes hooks. */ diff --git a/packages/hooks/src/createRunHook.js b/packages/hooks/src/createRunHook.js index da0e430871342..ec83026d4d0db 100644 --- a/packages/hooks/src/createRunHook.js +++ b/packages/hooks/src/createRunHook.js @@ -3,10 +3,10 @@ * registered to a hook of the specified type, optionally returning the final * value of the call chain. * - * @param {import('.').Hooks} hooks Hooks instance. - * @param {import('.').StoreKey} storeKey - * @param {boolean} [returnFirstArg=false] Whether each hook callback is expected to - * return its first argument. + * @param {import('.').Hooks} hooks Hooks instance. + * @param {import('.').StoreKey} storeKey + * @param {boolean} [returnFirstArg=false] Whether each hook callback is expected to + * return its first argument. * * @return {(hookName:string, ...args: unknown[]) => unknown} Function that runs hook callbacks. */ diff --git a/packages/hooks/src/validateHookName.js b/packages/hooks/src/validateHookName.js index de93ecdd306df..03409384dab59 100644 --- a/packages/hooks/src/validateHookName.js +++ b/packages/hooks/src/validateHookName.js @@ -1,11 +1,11 @@ /** * Validate a hookName string. * - * @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 `__`. + * @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 `__`. * - * @return {boolean} Whether the hook name is valid. + * @return {boolean} Whether the hook name is valid. */ function validateHookName( hookName ) { if ( 'string' !== typeof hookName || '' === hookName ) { diff --git a/packages/hooks/src/validateNamespace.js b/packages/hooks/src/validateNamespace.js index bd004482415f8..fdf451e1053d2 100644 --- a/packages/hooks/src/validateNamespace.js +++ b/packages/hooks/src/validateNamespace.js @@ -1,10 +1,10 @@ /** * Validate a namespace string. * - * @param {string} namespace The namespace to validate - should take the form - * `vendor/plugin/function`. + * @param {string} namespace The namespace to validate - should take the form + * `vendor/plugin/function`. * - * @return {boolean} Whether the namespace is valid. + * @return {boolean} Whether the namespace is valid. */ function validateNamespace( namespace ) { if ( 'string' !== typeof namespace || '' === namespace ) { diff --git a/packages/i18n/README.md b/packages/i18n/README.md index 7c4982a9caa77..0eda92fe80fba 100644 --- a/packages/i18n/README.md +++ b/packages/i18n/README.md @@ -39,7 +39,7 @@ _Parameters_ _Returns_ -- `I18n`: I18n instance +- `I18n`: I18n instance. <a name="defaultI18n" href="#defaultI18n">#</a> **defaultI18n** diff --git a/packages/i18n/src/create-i18n.js b/packages/i18n/src/create-i18n.js index 6bb5f47d72ad5..94b9c664db5c6 100644 --- a/packages/i18n/src/create-i18n.js +++ b/packages/i18n/src/create-i18n.js @@ -114,29 +114,30 @@ const I18N_HOOK_REGEXP = /^i18n\.(n?gettext|has_translation)(_|$)/; * An i18n instance * * @typedef I18n - * @property {GetLocaleData} getLocaleData Returns locale data by domain in a Jed-formatted JSON object shape. - * @property {SetLocaleData} setLocaleData Merges locale data into the Tannin instance by domain. Accepts data in a + * @property {GetLocaleData} getLocaleData Returns locale data by domain in a Jed-formatted JSON object shape. + * @property {SetLocaleData} setLocaleData Merges locale data into the Tannin instance by domain. Accepts data in a * Jed-formatted JSON object shape. * @property {ResetLocaleData} resetLocaleData Resets all current Tannin instance locale data and sets the specified * locale data for the domain. Accepts data in a Jed-formatted JSON object shape. - * @property {Subscribe} subscribe Subscribes to changes of Tannin locale data. - * @property {__} __ Retrieve the translation of text. - * @property {_x} _x Retrieve translated string with gettext context. - * @property {_n} _n Translates and retrieves the singular or plural form based on the supplied + * @property {Subscribe} subscribe Subscribes to changes of Tannin locale data. + * @property {__} __ Retrieve the translation of text. + * @property {_x} _x Retrieve translated string with gettext context. + * @property {_n} _n Translates and retrieves the singular or plural form based on the supplied * number. - * @property {_nx} _nx Translates and retrieves the singular or plural form based on the supplied + * @property {_nx} _nx Translates and retrieves the singular or plural form based on the supplied * number, with gettext context. - * @property {IsRtl} isRTL Check if current locale is RTL. - * @property {HasTranslation} hasTranslation Check if there is a translation for a given string. + * @property {IsRtl} isRTL Check if current locale is RTL. + * @property {HasTranslation} hasTranslation Check if there is a translation for a given string. */ /** * Create an i18n instance * - * @param {LocaleData} [initialData] Locale data configuration. - * @param {string} [initialDomain] Domain for which configuration applies. - * @param {Hooks} [hooks] Hooks implementation. - * @return {I18n} I18n instance + * @param {LocaleData} [initialData] Locale data configuration. + * @param {string} [initialDomain] Domain for which configuration applies. + * @param {Hooks} [hooks] Hooks implementation. + * + * @return {I18n} I18n instance. */ export const createI18n = ( initialData, initialDomain, hooks ) => { /** @@ -168,7 +169,7 @@ export const createI18n = ( initialData, initialDomain, hooks ) => { /** * @param {LocaleData} [data] - * @param {string} [domain] + * @param {string} [domain] */ const doSetLocaleData = ( data, domain = 'default' ) => { tannin.data[ domain ] = { @@ -408,9 +409,9 @@ export const createI18n = ( initialData, initialDomain, hooks ) => { * Filters the presence of a translation in the locale data. * * @param {boolean} hasTranslation Whether the translation is present or not.. - * @param {string} single The singular form of the translated text (used as key in locale data) - * @param {string} context Context information for the translators. - * @param {string} domain Text domain. Unique identifier for retrieving translated strings. + * @param {string} single The singular form of the translated text (used as key in locale data) + * @param {string} context Context information for the translators. + * @param {string} domain Text domain. Unique identifier for retrieving translated strings. */ result = /** @type { boolean } */ ( /** @type {*} */ hooks.applyFilters( diff --git a/packages/i18n/src/default-i18n.js b/packages/i18n/src/default-i18n.js index 5c6a2e11978a7..bdcb314943974 100644 --- a/packages/i18n/src/default-i18n.js +++ b/packages/i18n/src/default-i18n.js @@ -139,9 +139,9 @@ export const isRTL = i18n.isRTL.bind( i18n ); /** * Check if there is a translation for a given string (in singular form). * - * @param {string} single Singular form of the string to look up. + * @param {string} single Singular form of the string to look up. * @param {string} [context] Context information for the translators. - * @param {string} [domain] Domain to retrieve the translated text. + * @param {string} [domain] Domain to retrieve the translated text. * @return {boolean} Whether the translation exists or not. */ export const hasTranslation = i18n.hasTranslation.bind( i18n ); diff --git a/packages/i18n/src/sprintf.js b/packages/i18n/src/sprintf.js index 42fa94d8aa306..98c4bade268a1 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 https://www.npmjs.com/package/sprintf-js * 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 7447209d5ba71..df8ef91cd6769 100644 --- a/packages/keyboard-shortcuts/src/hooks/use-shortcut.js +++ b/packages/keyboard-shortcuts/src/hooks/use-shortcut.js @@ -12,9 +12,9 @@ import { store as keyboardShortcutsStore } from '../store'; /** * 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/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<string>} 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 797750e1bdad1..deee77808ca8c 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 ad25f01379fe2..59fa585e0ef97 100644 --- a/packages/notices/src/store/actions.js +++ b/packages/notices/src/store/actions.js @@ -11,11 +11,11 @@ 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 - * browser navigation. - * @property {?Function} onClick Optional function to invoke when action is - * triggered by user. + * @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 + * triggered by user. * */ diff --git a/packages/notices/src/store/selectors.js b/packages/notices/src/store/selectors.js index 0517d93171432..d03d8812d5338 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`, - * `info`, `error`, or `warning`. Defaults - * to `info`. - * @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 - * 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 - * user. Defaults to `true`. - * @property {string} type Type of notice, one of `default`, - * or `snackbar`. Defaults to `default`. - * @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 {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 + * assistive technologies. + * @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 + * user. Defaults to `true`. + * @property {string} type Type of notice, one of `default`, + * or `snackbar`. Defaults to `default`. + * @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. * */ 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-i18n/src/index.tsx b/packages/react-i18n/src/index.tsx index e111906134d49..01abc7570c94e 100644 --- a/packages/react-i18n/src/index.tsx +++ b/packages/react-i18n/src/index.tsx @@ -35,7 +35,7 @@ interface I18nContextProps { /** * Utility to make a new context value * - * @param i18n + * @param i18n */ function makeContextValue( i18n: I18n ): I18nContextProps { return { @@ -72,7 +72,7 @@ type I18nProviderProps = PropsWithChildren< { i18n: I18n } >; * You can also instantiate the provider without the `i18n` prop. In that case it will use the * default `I18n` instance exported from `@wordpress/i18n`. * - * @param props i18n provider props. + * @param props i18n provider props. * @return Children wrapped in the I18nProvider. */ export function I18nProvider( props: I18nProviderProps ): JSX.Element { @@ -128,7 +128,7 @@ type PropsAndI18n< P > = Pick< * export default withI18n( MyComponent ); * ``` * - * @param InnerComponent React component to be wrapped and receive the i18n functions like `__` + * @param InnerComponent React component to be wrapped and receive the i18n functions like `__` * @return The wrapped component */ export function withI18n< P extends I18nContextProps >( diff --git a/packages/react-native-bridge/index.js b/packages/react-native-bridge/index.js index a17ae6aad4a41..fde2f09856346 100644 --- a/packages/react-native-bridge/index.js +++ b/packages/react-native-bridge/index.js @@ -77,14 +77,14 @@ export function subscribeFeaturedImageIdNativeUpdated( callback ) { * When a media item exists as a local file and is to be uploaded, these are the generated events that are useful listening to. * see subscribeMediaSave for events during a save operation. * - * @param {Function} callback RN Callback function to be called with the following - * state and params: - * state: - * MEDIA_UPLOAD_STATE_SAVING: this is a progress update. Takes String mediaId, float progress. - * MEDIA_UPLOAD_STATE_SUCCEEDED: sent when one media is finished being saved. Takes String mediaId, String mediaUrl, String serverID - * (which is the remote id assigned to this file after having been uploaded). - * MEDIA_UPLOAD_STATE_FAILED: sent in case of saving failure (final state). Takes String mediaId. - * MEDIA_UPLOAD_STATE_RESET: sent when the progress and state needs be reset (a retry for example, for cleanup). Takes String mediaId. + * @param {Function} callback RN Callback function to be called with the following + * state and params: + * state: + * MEDIA_UPLOAD_STATE_SAVING: this is a progress update. Takes String mediaId, float progress. + * MEDIA_UPLOAD_STATE_SUCCEEDED: sent when one media is finished being saved. Takes String mediaId, String mediaUrl, String serverID + * (which is the remote id assigned to this file after having been uploaded). + * MEDIA_UPLOAD_STATE_FAILED: sent in case of saving failure (final state). Takes String mediaId. + * MEDIA_UPLOAD_STATE_RESET: sent when the progress and state needs be reset (a retry for example, for cleanup). Takes String mediaId. */ export function subscribeMediaUpload( callback ) { return gutenbergBridgeEvents.addListener( 'mediaUpload', callback ); @@ -96,20 +96,20 @@ export function subscribeMediaUpload( callback ) { * When a media item does not yet exist as a local file and is progressively being saved, these are the generated events that are useful listening to. * see subscribeMediaUpload for events during an upload operation. * - * @param {Function} callback RN Callback function to be called with the following - * state and params: - * Note that the first 4 states described are similar to upload events. - * state: - * MEDIA_SAVE_STATE_SAVING: this is a progress update. Takes String mediaId, float progress. - * MEDIA_SAVE_STATE_SUCCEEDED: sent when one media is finished being saved. Takes String mediaId, String mediaUrl. - * MEDIA_SAVE_STATE_FAILED: sent in case of saving failure (final state). Takes String mediaId. - * MEDIA_SAVE_STATE_RESET: sent when the progress and state needs be reset (a retry for example, for cleanup). Takes String mediaId. - * MEDIA_SAVE_FINAL_STATE_RESULT: used in media collections, sent when ALL media items in a collection have reached - * a final state (either FAILED or SUCCEEDED). Handy to know when to show a final state to the user, on - * a media collection based block when we don't know if there are still events to be received for other - * items in the collection. - * MEDIA_SAVE_MEDIAID_CHANGED: used when changing a media item id from a temporary id to a local file id, and then from a local file - * id to a remote file id. + * @param {Function} callback RN Callback function to be called with the following + * state and params: + * Note that the first 4 states described are similar to upload events. + * state: + * MEDIA_SAVE_STATE_SAVING: this is a progress update. Takes String mediaId, float progress. + * MEDIA_SAVE_STATE_SUCCEEDED: sent when one media is finished being saved. Takes String mediaId, String mediaUrl. + * MEDIA_SAVE_STATE_FAILED: sent in case of saving failure (final state). Takes String mediaId. + * MEDIA_SAVE_STATE_RESET: sent when the progress and state needs be reset (a retry for example, for cleanup). Takes String mediaId. + * MEDIA_SAVE_FINAL_STATE_RESULT: used in media collections, sent when ALL media items in a collection have reached + * a final state (either FAILED or SUCCEEDED). Handy to know when to show a final state to the user, on + * a media collection based block when we don't know if there are still events to be received for other + * items in the collection. + * MEDIA_SAVE_MEDIAID_CHANGED: used when changing a media item id from a temporary id to a local file id, and then from a local file + * id to a remote file id. */ export function subscribeMediaSave( callback ) { return gutenbergBridgeEvents.addListener( 'mediaSave', callback ); @@ -146,7 +146,7 @@ export function subscribeShowNotice( 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. */ @@ -164,10 +164,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<string>} 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<string>} 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( @@ -183,10 +183,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, @@ -300,8 +300,8 @@ export function showXpostSuggestions() { * For example, a mediaFiles collection editor can make special handling of visualization * in this regard. * - * @param {Array<Map>} mediaFiles the mediaFiles attribute of the block, containing data about each media item. - * @param {string} blockClientId the clientId of the block. + * @param {Array<Map>} mediaFiles the mediaFiles attribute of the block, containing data about each media item. + * @param {string} blockClientId the clientId of the block. */ export function requestMediaFilesEditorLoad( mediaFiles, blockClientId ) { RNReactNativeGutenbergBridge.requestMediaFilesEditorLoad( @@ -357,8 +357,8 @@ export function requestMediaFilesSaveCancelDialog( mediaFiles ) { * Request the host app to listen to mediaFiles collection based block replacement signals * in case such an event was enqueued * - * @param {Array<Map>} mediaFiles the mediaFiles attribute of the block, containing data about each media item. - * @param {string} blockClientId the clientId of the block. + * @param {Array<Map>} mediaFiles the mediaFiles attribute of the block, containing data about each media item. + * @param {string} blockClientId the clientId of the block. */ export function mediaFilesBlockReplaceSync( mediaFiles, blockClientId ) { RNReactNativeGutenbergBridge.mediaFilesBlockReplaceSync( diff --git a/packages/react-native-editor/sass-transformer.js b/packages/react-native-editor/sass-transformer.js index eb471eb024fac..5f3ab6f695398 100644 --- a/packages/react-native-editor/sass-transformer.js +++ b/packages/react-native-editor/sass-transformer.js @@ -5,9 +5,9 @@ * https://github.com/kristerkari/react-native-sass-transformer * * The MIT License (MIT) - + * * Copyright (c) 2018 Krister Kari - + * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal * in the Software without restriction, including without limitation the rights 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/reusable-blocks/src/store/actions.js b/packages/reusable-blocks/src/store/actions.js index b9c12490f9630..b9642bc32be02 100644 --- a/packages/reusable-blocks/src/store/actions.js +++ b/packages/reusable-blocks/src/store/actions.js @@ -38,7 +38,7 @@ export function* __experimentalDeleteReusableBlock( id ) { /** * Returns an action descriptor for SET_EDITING_REUSABLE_BLOCK action. * - * @param {string} clientId The clientID of the reusable block to target. + * @param {string} clientId The clientID of the reusable block to target. * @param {boolean} isEditing Whether the block should be in editing state. * @return {Object} Action descriptor. */ diff --git a/packages/reusable-blocks/src/store/controls.js b/packages/reusable-blocks/src/store/controls.js index 373fbc698931f..e430688684305 100644 --- a/packages/reusable-blocks/src/store/controls.js +++ b/packages/reusable-blocks/src/store/controls.js @@ -24,7 +24,7 @@ import { store as reusableBlocksStore } from './index.js'; /** * Convert a reusable block to a static block effect handler * - * @param {string} clientId Block ID. + * @param {string} clientId Block ID. * @return {Object} control descriptor. */ export function convertBlockToStatic( clientId ) { @@ -37,8 +37,8 @@ export function convertBlockToStatic( clientId ) { /** * Convert a static block to a reusable block effect handler * - * @param {Array} clientIds Block IDs. - * @param {string} title Reusable block title. + * @param {Array} clientIds Block IDs. + * @param {string} title Reusable block title. * @return {Object} control descriptor. */ export function convertBlocksToReusable( clientIds, title ) { diff --git a/packages/reusable-blocks/src/store/selectors.js b/packages/reusable-blocks/src/store/selectors.js index ac290c59a1cd6..37d82f83c602b 100644 --- a/packages/reusable-blocks/src/store/selectors.js +++ b/packages/reusable-blocks/src/store/selectors.js @@ -1,7 +1,7 @@ /** * Returns true if reusable block is in the editing state. * - * @param {Object} state Global application state. + * @param {Object} state Global application state. * @param {number} clientId the clientID of the block. * @return {boolean} Whether the reusable block is in the editing state. */ diff --git a/packages/rich-text/src/component/use-format-types.js b/packages/rich-text/src/component/use-format-types.js index 13b0a852e1553..117ddd45d6e82 100644 --- a/packages/rich-text/src/component/use-format-types.js +++ b/packages/rich-text/src/component/use-format-types.js @@ -35,11 +35,11 @@ const interactiveContentTags = new Set( [ * This hook provides RichText with the `formatTypes` and its derived props from * experimental format type settings. * - * @param {Object} $0 Options - * @param {string} $0.clientId Block client ID. - * @param {string} $0.identifier Block attribute. + * @param {Object} $0 Options + * @param {string} $0.clientId Block client ID. + * @param {string} $0.identifier Block attribute. * @param {boolean} $0.withoutInteractiveFormatting Whether to clean the interactive formattings or not. - * @param {Array} $0.allowedFormats Allowed formats + * @param {Array} $0.allowedFormats Allowed formats */ export function useFormatTypes( { clientId, diff --git a/packages/rich-text/src/create.js b/packages/rich-text/src/create.js index a64c5d3bf3c58..fe7161433b671 100644 --- a/packages/rich-text/src/create.js +++ b/packages/rich-text/src/create.js @@ -141,17 +141,17 @@ 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.preserveWhiteSpace] Whether or not to collapse white + * space characters. * @param {boolean} [$1.__unstableIsEditableTree] * * @return {RichTextValue} A rich text value. diff --git a/packages/rich-text/src/get-line-index.js b/packages/rich-text/src/get-line-index.js index 8dc9de3973ec7..15590304ecadd 100644 --- a/packages/rich-text/src/get-line-index.js +++ b/packages/rich-text/src/get-line-index.js @@ -10,10 +10,10 @@ 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 {RichTextValue} 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 {RichTextValue} 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. * * @return {number|void} The line index. Undefined if not found. */ diff --git a/packages/rich-text/src/indent-list-items.js b/packages/rich-text/src/indent-list-items.js index e6b380bac16e1..cbcec5126e4bb 100644 --- a/packages/rich-text/src/indent-list-items.js +++ b/packages/rich-text/src/indent-list-items.js @@ -12,9 +12,9 @@ import { canIndentListItems } from './can-indent-list-items'; /** * Gets the line index of the first previous list item with higher indentation. * - * @param {RichTextValue} value Value to search. - * @param {number} lineIndex Line index of the list item to compare - * with. + * @param {RichTextValue} value Value to search. + * @param {number} lineIndex Line index of the list item to compare + * with. * * @return {number|void} The line index. */ diff --git a/packages/rich-text/src/is-empty.js b/packages/rich-text/src/is-empty.js index 40417bbf62896..1bc0a3525fce9 100644 --- a/packages/rich-text/src/is-empty.js +++ b/packages/rich-text/src/is-empty.js @@ -21,7 +21,7 @@ export function isEmpty( { text } ) { * Check if the current collapsed selection is on an empty line in case of a * multiline value. * - * @param {RichTextValue} value Value te check. + * @param {RichTextValue} value Value te check. * * @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 e3c096804e0ee..b271091cbe6a0 100644 --- a/packages/rich-text/src/register-format-type.js +++ b/packages/rich-text/src/register-format-type.js @@ -23,8 +23,8 @@ import { store as richTextStore } from './store'; * 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/replace.js b/packages/rich-text/src/replace.js index 6b4c0995c4fa0..98579a7bae739 100644 --- a/packages/rich-text/src/replace.js +++ b/packages/rich-text/src/replace.js @@ -10,8 +10,8 @@ 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 {RichTextValue} value The value to modify. - * @param {RegExp|string} pattern A RegExp object or literal. Can also be + * @param {RichTextValue} 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 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-tree.js b/packages/rich-text/src/to-tree.js index b41820a8ee8ec..91d6bc08fc414 100644 --- a/packages/rich-text/src/to-tree.js +++ b/packages/rich-text/src/to-tree.js @@ -14,17 +14,17 @@ 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 - * attributes. - * @param {boolean} $1.object Whether or not it is an object - * format. - * @param {boolean} $1.boundaryClass Whether or not to apply a boundary - * class. - * @return {Object} Information to be used for - * element creation. + * @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 Whether or not it is an object + * format. + * @param {boolean} $1.boundaryClass Whether or not to apply a boundary + * class. + * + * @return {Object} Information to be used for element creation. */ function fromFormat( { type, diff --git a/packages/rich-text/src/update-formats.js b/packages/rich-text/src/update-formats.js index 2bc83d14d27ea..65407a4a490e1 100644 --- a/packages/rich-text/src/update-formats.js +++ b/packages/rich-text/src/update-formats.js @@ -10,11 +10,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 {RichTextValue} $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 {RichTextValue} $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 {RichTextValue} Mutated value. */ diff --git a/packages/scripts/scripts/check-licenses.js b/packages/scripts/scripts/check-licenses.js index 34073cd05bdfe..0628fdc2389ce 100644 --- a/packages/scripts/scripts/check-licenses.js +++ b/packages/scripts/scripts/check-licenses.js @@ -124,7 +124,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 859785d44544a..c47c33813c16b 100644 --- a/packages/url/src/add-query-args.js +++ b/packages/url/src/add-query-args.js @@ -9,9 +9,9 @@ import { buildQueryString } from './build-query-string'; * 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, - * only the resulting querystring is returned. - * @param {Object} [args] Query arguments to apply to URL. + * @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. * * @example * ```js diff --git a/packages/url/src/filter-url-for-display.js b/packages/url/src/filter-url-for-display.js index fd3eccc99cbf7..2d3247e6d1da9 100644 --- a/packages/url/src/filter-url-for-display.js +++ b/packages/url/src/filter-url-for-display.js @@ -1,7 +1,7 @@ /** * Returns a URL for display. * - * @param {string} url Original URL. + * @param {string} url Original URL. * @param {number|null} maxLength URL length. * * @example 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 6ef490d0ff1d9..5c3f2b0c9049d 100644 --- a/packages/viewport/src/with-viewport-match.native.js +++ b/packages/viewport/src/with-viewport-match.native.js @@ -21,7 +21,7 @@ import { store } from './store'; * * @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/widgets/src/utils.js b/packages/widgets/src/utils.js index cd6a0409ba5d1..75b1f3d08140e 100644 --- a/packages/widgets/src/utils.js +++ b/packages/widgets/src/utils.js @@ -4,11 +4,11 @@ * Get the internal widget id from block. * * @typedef {Object} Attributes - * @property {string} __internalWidgetId The internal widget id. + * @property {string} __internalWidgetId The internal widget id. * @typedef {Object} Block - * @property {Attributes} attributes The attributes of the block. + * @property {Attributes} attributes The attributes of the block. * - * @param {Block} block The block. + * @param {Block} block The block. * @return {string} The internal widget id. */ export function getWidgetIdFromBlock( block ) { @@ -18,7 +18,7 @@ export function getWidgetIdFromBlock( block ) { /** * Add internal widget id to block's attributes. * - * @param {Block} block The block. + * @param {Block} block The block. * @param {string} widgetId The widget id. * @return {Block} The updated block. */ diff --git a/test/unit/config/matchers/to-match-style-diff-snapshot.js b/test/unit/config/matchers/to-match-style-diff-snapshot.js index 6a4f6183ca1ff..7c810aad1736f 100644 --- a/test/unit/config/matchers/to-match-style-diff-snapshot.js +++ b/test/unit/config/matchers/to-match-style-diff-snapshot.js @@ -8,7 +8,7 @@ const getStyleSheets = () => /** * - * @param {Element} element + * @param {Element} element * @param {HTMLStyleElement[]} styleSheets */ const getStyleRulesForElement = ( element, styleSheets ) => { @@ -60,7 +60,7 @@ const cleanStyleRule = ( rule ) => { /** * @param {Element} received * @param {Element} expected - * @param {string} testName + * @param {string} testName */ function toMatchStyleDiffSnapshot( received, expected, testName ) { const styleSheets = getStyleSheets();