From 65d25efcd576e48097abfac8ff6ddffe98078307 Mon Sep 17 00:00:00 2001 From: Derek Sifford Date: Thu, 1 Aug 2019 21:41:10 -0400 Subject: [PATCH 1/2] chore: fix all JSDoc eslint errors/warnings across the entire repository --- bin/commander.js | 2 +- .../developers/data/data-core-block-editor.md | 4 +- package-lock.json | 18 +++ packages/annotations/src/format/annotation.js | 9 +- packages/annotations/src/store/actions.js | 19 ++- packages/autop/src/index.js | 2 +- packages/block-editor/README.md | 4 +- .../src/components/block-list/index.js | 6 - .../src/components/block-title/index.js | 1 + .../src/components/colors/utils.js | 30 ++-- .../src/components/colors/with-colors.js | 14 +- .../components/font-sizes/with-font-sizes.js | 5 +- .../components/ignore-nested-events/index.js | 2 - .../src/components/inserter/index.js | 2 + .../multi-select-scroll-into-view/index.js | 2 - packages/block-editor/src/hooks/align.js | 4 +- packages/block-editor/src/hooks/anchor.js | 2 +- .../src/hooks/custom-class-name.js | 2 +- packages/block-editor/src/store/actions.js | 6 +- packages/block-editor/src/store/reducer.js | 2 +- packages/block-editor/src/store/selectors.js | 5 +- .../src/utils/transform-styles/ast/parse.js | 131 +++++++++--------- .../ast/stringify/compiler.js | 4 - .../transform-styles/ast/stringify/index.js | 3 +- .../transforms/url-rewrite.js | 1 - .../utils/transform-styles/transforms/wrap.js | 2 +- packages/block-library/src/columns/edit.js | 4 +- packages/block-library/src/embed/util.js | 8 +- packages/block-library/src/table/edit.js | 1 + packages/block-library/src/table/state.js | 5 + .../src/index.js | 6 +- packages/blocks/README.md | 2 + .../raw-handling/image-corrector.native.js | 2 +- packages/blocks/src/api/raw-handling/index.js | 1 + .../src/api/raw-handling/paste-handler.js | 1 + packages/blocks/src/api/registration.js | 36 ++--- packages/blocks/src/store/reducer.js | 2 +- packages/components/src/autocomplete/index.js | 26 ++-- packages/components/src/color-picker/index.js | 2 +- packages/components/src/draggable/index.js | 2 - .../src/higher-order/with-notices/index.js | 30 ++-- packages/components/src/notice/list.js | 18 +-- packages/components/src/placeholder/index.js | 10 +- packages/components/src/popover/index.js | 4 +- packages/components/src/popover/utils.js | 2 - packages/components/src/snackbar/list.js | 18 +-- packages/components/src/toolbar/index.js | 9 +- packages/components/src/tooltip/index.js | 2 +- packages/core-data/src/controls.js | 1 + .../src/queried-data/get-query-parts.js | 2 +- packages/data-controls/src/index.js | 9 +- packages/data/README.md | 8 +- packages/data/src/factory.js | 8 +- packages/data/src/index.js | 10 +- .../src/namespace-store/metadata/reducer.js | 2 +- .../data/src/plugins/persistence/index.js | 3 +- packages/data/src/promise-middleware.js | 2 +- packages/data/src/registry.js | 8 +- packages/date/src/index.js | 6 +- .../util.js | 10 +- packages/docgen/src/engine.js | 8 +- packages/e2e-test-utils/README.md | 8 +- .../src/are-pre-publish-checks-enabled.js | 1 + .../e2e-test-utils/src/get-block-setting.js | 1 + .../src/mocks/create-embedding-matcher.js | 4 +- .../src/mocks/create-url-matcher.js | 2 +- .../src/mocks/mock-or-transform.js | 4 +- .../e2e-test-utils/src/set-post-content.js | 1 + packages/e2e-test-utils/src/wp-data-select.js | 1 + .../components/editor-initialization/utils.js | 6 +- packages/edit-post/src/store/actions.js | 2 +- packages/edit-post/src/store/constants.js | 3 + packages/edit-widgets/src/store/actions.js | 4 +- packages/edit-widgets/src/store/constants.js | 1 + .../src/components/autocompleters/user.js | 8 +- .../components/post-preview-button/index.js | 2 +- .../post-type-support-check/index.js | 3 +- packages/editor/src/store/actions.native.js | 2 +- packages/editor/src/store/constants.js | 1 + packages/editor/src/store/reducer.js | 2 +- packages/element/README.md | 2 + packages/element/src/raw-html.js | 2 + .../eslint-plugin/rules/gutenberg-phase.js | 2 +- packages/format-library/src/link/utils.js | 7 +- .../src/components/media-upload/index.js | 2 +- packages/notices/src/store/selectors.js | 6 +- packages/redux-routine/src/runtime.js | 4 +- packages/rich-text/README.md | 8 +- packages/rich-text/src/component/index.js | 10 +- .../rich-text/src/component/index.native.js | 2 +- packages/rich-text/src/split.js | 8 +- packages/wordcount/README.md | 6 +- packages/wordcount/src/index.js | 6 +- test/native/__mocks__/styleMock.js | 4 - test/native/jest.config.js | 3 - 95 files changed, 353 insertions(+), 325 deletions(-) diff --git a/bin/commander.js b/bin/commander.js index bb5f508ca56965..091e8156611bdb 100755 --- a/bin/commander.js +++ b/bin/commander.js @@ -57,7 +57,7 @@ async function askForConfirmationToContinue( message, isDefault = true, abortMes * * @param {string} name Step name. * @param {string} abortMessage Abort message. - * @param {function} handler Step logic. + * @param {Function} handler Step logic. */ async function runStep( name, abortMessage, handler ) { try { diff --git a/docs/designers-developers/developers/data/data-core-block-editor.md b/docs/designers-developers/developers/data/data-core-block-editor.md index 1b42d76df3e3b4..e7befe38543b82 100644 --- a/docs/designers-developers/developers/data/data-core-block-editor.md +++ b/docs/designers-developers/developers/data/data-core-block-editor.md @@ -203,7 +203,7 @@ on each call _Parameters_ - _state_ `Object`: Editor state. -- _rootClientId_ `?String`: Optional root client ID of block list. +- _rootClientId_ `?string`: Optional root client ID of block list. _Returns_ @@ -299,7 +299,7 @@ The number returned includes nested blocks. _Parameters_ - _state_ `Object`: Global application state. -- _blockName_ `?String`: Optional block name, if specified only blocks of that type will be counted. +- _blockName_ `?string`: Optional block name, if specified only blocks of that type will be counted. _Returns_ diff --git a/package-lock.json b/package-lock.json index 04093ff7f7b4fa..80b9b46734c736 100644 --- a/package-lock.json +++ b/package-lock.json @@ -4078,7 +4078,25 @@ "eslint-plugin-jsx-a11y": "^6.2.1", "eslint-plugin-react": "^7.12.4", "eslint-plugin-react-hooks": "^1.6.0", + "globals": "^12.0.0", "requireindex": "^1.2.0" + }, + "dependencies": { + "globals": { + "version": "12.0.0", + "resolved": "https://registry.npmjs.org/globals/-/globals-12.0.0.tgz", + "integrity": "sha512-c9xoi32iDwlETiyYfO0pd3M8GcEuytJinSoqq7k3fz4H8p2p31NyfKr7JVd7Y0QvmtWcWXcwqW4L33eeDYgh1A==", + "dev": true, + "requires": { + "type-fest": "^0.6.0" + } + }, + "type-fest": { + "version": "0.6.0", + "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.6.0.tgz", + "integrity": "sha512-q+MB8nYR1KDLrgr4G5yemftpMC7/QLqVndBmEEdqzmNj5dcFOO4Oo8qlwZE3ULT3+Zim1F8Kq4cBnikNhlCMlg==", + "dev": true + } } }, "@wordpress/format-library": { diff --git a/packages/annotations/src/format/annotation.js b/packages/annotations/src/format/annotation.js index a2f6f2973c7268..46dd6e279fa3ba 100644 --- a/packages/annotations/src/format/annotation.js +++ b/packages/annotations/src/format/annotation.js @@ -92,10 +92,11 @@ function retrieveAnnotationPositions( formats ) { /** * Updates annotations in the state based on positions retrieved from RichText. * - * @param {Array} annotations The annotations that are currently applied. - * @param {Array} positions The current positions of the given annotations. - * @param {Function} removeAnnotation Function to remove an annotation from the state. - * @param {Function} updateAnnotationRange Function to update an annotation range in the state. + * @param {Array} annotations The annotations that are currently applied. + * @param {Array} positions The current positions of the given annotations. + * @param {Object} actions + * @param {Function} actions.removeAnnotation Function to remove an annotation from the state. + * @param {Function} actions.updateAnnotationRange Function to update an annotation range in the state. */ function updateAnnotationsWithPositions( annotations, positions, { removeAnnotation, updateAnnotationRange } ) { annotations.forEach( ( currentAnnotation ) => { diff --git a/packages/annotations/src/store/actions.js b/packages/annotations/src/store/actions.js index 96598022d5a7c1..8135ca3e32066b 100644 --- a/packages/annotations/src/store/actions.js +++ b/packages/annotations/src/store/actions.js @@ -13,16 +13,15 @@ import uuid from 'uuid/v4'; * * The `range` property is only relevant if the selector is 'range'. * - * @param {Object} annotation The annotation to add. - * @param {string} blockClientId The blockClientId to add the annotation to. - * @param {string} richTextIdentifier Identifier for the RichText instance the annotation applies to. - * @param {Object} range The range at which to apply this annotation. - * @param {number} range.start The offset where the annotation should start. - * @param {number} range.end The offset where the annotation should end. - * @param {string} [selector="range"] The way to apply this annotation. - * @param {string} [source="default"] The source that added the annotation. - * @param {string} [id=uuid()] The ID the annotation should have. - * Generates a UUID by default. + * @param {Object} annotation The annotation to add. + * @param {string} annotation.blockClientId The blockClientId to add the annotation to. + * @param {string} annotation.richTextIdentifier Identifier for the RichText instance the annotation applies to. + * @param {Object} annotation.range The range at which to apply this annotation. + * @param {number} annotation.range.start The offset where the annotation should start. + * @param {number} annotation.range.end The offset where the annotation should end. + * @param {string} annotation.[selector="range"] The way to apply this annotation. + * @param {string} annotation.[source="default"] The source that added the annotation. + * @param {string} annotation.[id] The ID the annotation should have. Generates a UUID by default. * * @return {Object} Action object. */ diff --git a/packages/autop/src/index.js b/packages/autop/src/index.js index 3e3e2fedc36b8c..1225d5c6637d8c 100644 --- a/packages/autop/src/index.js +++ b/packages/autop/src/index.js @@ -1,7 +1,7 @@ /** * The regular expression for an HTML element. * - * @type {String} + * @type {string} */ const htmlSplitRegex = ( () => { /* eslint-disable no-multi-spaces */ diff --git a/packages/block-editor/README.md b/packages/block-editor/README.md index 63718286e9bb87..b1028cbc28e64d 100644 --- a/packages/block-editor/README.md +++ b/packages/block-editor/README.md @@ -444,7 +444,7 @@ export default compose( _Parameters_ -- _colorTypes_ `...(object|string)`: The arguments can be strings or objects. If the argument is an object, it should contain the color attribute name as key and the color context as value. If the argument is a string the value should be the color attribute name, the color context is computed by applying a kebab case transform to the value. Color context represents the context/place where the color is going to be used. The class name of the color is generated using 'has' followed by the color name and ending with the color context all in kebab case e.g: has-green-background-color. +- _colorTypes_ `...(Object|string)`: The arguments can be strings or objects. If the argument is an object, it should contain the color attribute name as key and the color context as value. If the argument is a string the value should be the color attribute name, the color context is computed by applying a kebab case transform to the value. Color context represents the context/place where the color is going to be used. The class name of the color is generated using 'has' followed by the color name and ending with the color context all in kebab case e.g: has-green-background-color. _Returns_ @@ -457,7 +457,7 @@ font size value retrieval, and font size change handling. _Parameters_ -- _args_ `...(object|string)`: The arguments should all be strings Each string contains the font size attribute name e.g: 'fontSize'. +- _fontSizeNames_ `...(Object|string)`: The arguments should all be strings. Each string contains the font size attribute name e.g: 'fontSize'. _Returns_ diff --git a/packages/block-editor/src/components/block-list/index.js b/packages/block-editor/src/components/block-list/index.js index 3e65a52fd3b2ec..e3f68637dbb91d 100644 --- a/packages/block-editor/src/components/block-list/index.js +++ b/packages/block-editor/src/components/block-list/index.js @@ -87,8 +87,6 @@ class BlockList extends Component { * multi-selection. * * @param {MouseEvent} event A mousemove event object. - * - * @return {void} */ onPointerMove( { clientY } ) { // We don't start multi-selection until the mouse starts moving, so as @@ -116,8 +114,6 @@ class BlockList extends Component { * in response to a mousedown event occurring in a rendered block. * * @param {string} clientId Client ID of block where mousedown occurred. - * - * @return {void} */ onSelectionStart( clientId ) { if ( ! this.props.isSelectionEnabled ) { @@ -173,8 +169,6 @@ class BlockList extends Component { /** * Handles a mouseup event to end the current cursor multi-selection. - * - * @return {void} */ onSelectionEnd() { // Cancel throttled calls. diff --git a/packages/block-editor/src/components/block-title/index.js b/packages/block-editor/src/components/block-title/index.js index 99519655419e12..6834df11498922 100644 --- a/packages/block-editor/src/components/block-title/index.js +++ b/packages/block-editor/src/components/block-title/index.js @@ -14,6 +14,7 @@ import { getBlockType } from '@wordpress/blocks'; * * ``` * + * @param {Object} props * @param {?string} props.name Block name. * * @return {?string} Block title. diff --git a/packages/block-editor/src/components/colors/utils.js b/packages/block-editor/src/components/colors/utils.js index 67be0eed5a2517..764b02acde2822 100644 --- a/packages/block-editor/src/components/colors/utils.js +++ b/packages/block-editor/src/components/colors/utils.js @@ -30,14 +30,14 @@ export const getColorObjectByAttributeValues = ( colors, definedColor, customCol }; /** -* 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. -* -* @return {?Object} Color object included in the colors array whose color property equals colorValue. -* Returns undefined if no color object matches this requirement. -*/ + * 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. + * + * @return {?Object} Color object included in the colors array whose color property equals colorValue. + * Returns undefined if no color object matches this requirement. + */ export const getColorObjectByColorValue = ( colors, colorValue ) => { return find( colors, { color: colorValue } ); }; @@ -60,13 +60,13 @@ export function getColorClassName( colorContextName, colorSlug ) { } /** -* Given an array of color objects and a color value returns the color value of the most readable color in the array. -* -* @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 {string} String with the color value of the most readable color. -*/ + * Given an array of color objects and a color value returns the color value of the most readable color in the array. + * + * @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 {string} String with the color value of the most readable color. + */ export function getMostReadableColor( colors, colorValue ) { return tinycolor.mostReadable( colorValue, diff --git a/packages/block-editor/src/components/colors/with-colors.js b/packages/block-editor/src/components/colors/with-colors.js index 516a5a023414fd..b6f33b1b8590f7 100644 --- a/packages/block-editor/src/components/colors/with-colors.js +++ b/packages/block-editor/src/components/colors/with-colors.js @@ -23,7 +23,7 @@ const DEFAULT_COLORS = []; * * @param {Array} colorsArray An array of color objects. * - * @return {function} The higher order component. + * @return {Function} The higher order component. */ const withCustomColorPalette = ( colorsArray ) => createHigherOrderComponent( ( WrappedComponent ) => ( props ) => ( @@ -33,7 +33,7 @@ const withCustomColorPalette = ( colorsArray ) => createHigherOrderComponent( ( * Higher order component factory for injecting the editor colors as the * `colors` prop in the `withColors` HOC. * - * @return {function} The higher order component. + * @return {Function} The higher order component. */ const withEditorColorPalette = () => withSelect( ( select ) => { const settings = select( 'core/block-editor' ).getSettings(); @@ -110,10 +110,10 @@ function createColorHOC( colorTypes, withColorPalette ) { const previousColorObject = previousState[ colorAttributeName ]; const previousColor = get( previousColorObject, [ 'color' ] ); /** - * The "and previousColorObject" condition checks that a previous color object was already computed. - * At the start previousColorObject and colorValue are both equal to undefined - * bus as previousColorObject does not exist we should compute the object. - */ + * The "and previousColorObject" condition checks that a previous color object was already computed. + * At the start previousColorObject and colorValue are both equal to undefined + * bus as previousColorObject does not exist we should compute the object. + */ if ( previousColor === colorObject.color && previousColorObject ) { newState[ colorAttributeName ] = previousColorObject; } else { @@ -187,7 +187,7 @@ export function createCustomColorsHOC( colorsArray ) { * ); * ``` * - * @param {...(object|string)} colorTypes The arguments can be strings or objects. If the argument is an object, + * @param {...(Object|string)} colorTypes The arguments can be strings or objects. If the argument is an object, * it should contain the color attribute name as key and the color context as value. * If the argument is a string the value should be the color attribute name, * the color context is computed by applying a kebab case transform to the value. diff --git a/packages/block-editor/src/components/font-sizes/with-font-sizes.js b/packages/block-editor/src/components/font-sizes/with-font-sizes.js index 147d66df20c388..f64fe8d4f76006 100644 --- a/packages/block-editor/src/components/font-sizes/with-font-sizes.js +++ b/packages/block-editor/src/components/font-sizes/with-font-sizes.js @@ -19,8 +19,9 @@ import { getFontSize, getFontSizeClass } from './utils'; * Higher-order component, which handles font size logic for class generation, * font size value retrieval, and font size change handling. * - * @param {...(object|string)} args The arguments should all be strings - * Each string contains the font size attribute name e.g: 'fontSize'. + * @param {...(Object|string)} fontSizeNames The arguments should all be strings. + * Each string contains the font size + * attribute name e.g: 'fontSize'. * * @return {Function} Higher-order component. */ diff --git a/packages/block-editor/src/components/ignore-nested-events/index.js b/packages/block-editor/src/components/ignore-nested-events/index.js index 42f902b3e61c95..2592ba3abd0527 100644 --- a/packages/block-editor/src/components/ignore-nested-events/index.js +++ b/packages/block-editor/src/components/ignore-nested-events/index.js @@ -39,8 +39,6 @@ export class IgnoreNestedEvents extends Component { * it has not already been handled by a descendant IgnoreNestedEvents. * * @param {Event} event Event object. - * - * @return {void} */ proxyEvent( event ) { const isHandled = !! event.nativeEvent._blockHandled; diff --git a/packages/block-editor/src/components/inserter/index.js b/packages/block-editor/src/components/inserter/index.js index 4b842b4b7b3c59..98430b9345d088 100644 --- a/packages/block-editor/src/components/inserter/index.js +++ b/packages/block-editor/src/components/inserter/index.js @@ -46,6 +46,7 @@ class Inserter extends Component { /** * Render callback to display Dropdown toggle element. * + * @param {Object} options * @param {Function} options.onToggle Callback to invoke when toggle is * pressed. * @param {boolean} options.isOpen Whether dropdown is currently open. @@ -64,6 +65,7 @@ class Inserter extends Component { /** * Render callback to display Dropdown content element. * + * @param {Object} options * @param {Function} options.onClose Callback to invoke when dropdown is * closed. * diff --git a/packages/block-editor/src/components/multi-select-scroll-into-view/index.js b/packages/block-editor/src/components/multi-select-scroll-into-view/index.js index e49a90a520cbee..240a6dfaadc3ef 100644 --- a/packages/block-editor/src/components/multi-select-scroll-into-view/index.js +++ b/packages/block-editor/src/components/multi-select-scroll-into-view/index.js @@ -25,8 +25,6 @@ class MultiSelectScrollIntoView extends Component { /** * Ensures that if a multi-selection exists, the extent of the selection is * visible within the nearest scrollable container. - * - * @return {void} */ scrollIntoView() { const { extentClientId } = this.props; diff --git a/packages/block-editor/src/hooks/align.js b/packages/block-editor/src/hooks/align.js index ca0a019d5cc9e6..635db6b65f68e3 100644 --- a/packages/block-editor/src/hooks/align.js +++ b/packages/block-editor/src/hooks/align.js @@ -23,7 +23,7 @@ import { BlockControls, BlockAlignmentToolbar } from '../components'; * * @constant * @type {string[]} -*/ + */ const ALL_ALIGNMENTS = [ 'left', 'center', 'right', 'wide', 'full' ]; /** @@ -33,7 +33,7 @@ const ALL_ALIGNMENTS = [ 'left', 'center', 'right', 'wide', 'full' ]; * * @constant * @type {string[]} -*/ + */ const WIDE_ALIGNMENTS = [ 'wide', 'full' ]; /** diff --git a/packages/block-editor/src/hooks/anchor.js b/packages/block-editor/src/hooks/anchor.js index 3651346a96caf1..9b78c39bbfeb02 100644 --- a/packages/block-editor/src/hooks/anchor.js +++ b/packages/block-editor/src/hooks/anchor.js @@ -56,7 +56,7 @@ export function addAttribute( settings ) { * Override the default edit UI to include a new block inspector control for * assigning the anchor ID, if block supports anchor. * - * @param {function|Component} BlockEdit Original component. + * @param {Function|Component} BlockEdit Original component. * * @return {string} Wrapped component. */ diff --git a/packages/block-editor/src/hooks/custom-class-name.js b/packages/block-editor/src/hooks/custom-class-name.js index d7147a3693c30a..bac77a37ea42a2 100644 --- a/packages/block-editor/src/hooks/custom-class-name.js +++ b/packages/block-editor/src/hooks/custom-class-name.js @@ -47,7 +47,7 @@ export function addAttribute( settings ) { * Override the default edit UI to include a new block inspector control for * assigning the custom class name, if block supports custom class name. * - * @param {function|Component} BlockEdit Original component. + * @param {Function|Component} BlockEdit Original component. * * @return {string} Wrapped component. */ diff --git a/packages/block-editor/src/store/actions.js b/packages/block-editor/src/store/actions.js index 4dafaa291fcf31..d9eeefa75423d2 100644 --- a/packages/block-editor/src/store/actions.js +++ b/packages/block-editor/src/store/actions.js @@ -208,7 +208,7 @@ export function clearSelectedBlock() { * * @param {boolean} [isSelectionEnabled=true] Whether block selection should * be enabled. - + * * @return {Object} Action object. */ export function toggleSelection( isSelectionEnabled = true ) { @@ -227,7 +227,7 @@ export function toggleSelection( isSelectionEnabled = true ) { * @param {number} indexToSelect Index of replacement block to * select. * - * @yields {Object} Action object. + * @yield {Object} Action object. */ export function* replaceBlocks( clientIds, blocks, indexToSelect ) { clientIds = castArray( clientIds ); @@ -303,7 +303,7 @@ export const moveBlocksUp = createOnMove( 'MOVE_BLOCKS_UP' ); * @param {?string} toRootClientId Root client ID destination. * @param {number} index The index to move the block into. * - * @yields {Object} Action object. + * @yield {Object} Action object. */ export function* moveBlockToPosition( clientId, fromRootClientId = '', toRootClientId = '', index ) { const templateLock = yield select( diff --git a/packages/block-editor/src/store/reducer.js b/packages/block-editor/src/store/reducer.js index df81bd5df22f0b..9a1705a0ba8b29 100644 --- a/packages/block-editor/src/store/reducer.js +++ b/packages/block-editor/src/store/reducer.js @@ -581,7 +581,7 @@ const withSaveReusableBlock = ( reducer ) => ( state, action ) => { * @param {Object} state Current state. * @param {Object} action Dispatched action. * - * @returns {Object} Updated state. + * @return {Object} Updated state. */ export const blocks = flow( combineReducers, diff --git a/packages/block-editor/src/store/selectors.js b/packages/block-editor/src/store/selectors.js index 5e8771ff94935b..45e640a2fd9e10 100644 --- a/packages/block-editor/src/store/selectors.js +++ b/packages/block-editor/src/store/selectors.js @@ -169,7 +169,7 @@ export const __unstableGetBlockWithoutInnerBlocks = createSelector( * on each call * * @param {Object} state Editor state. - * @param {?String} rootClientId Optional root client ID of block list. + * @param {?string} rootClientId Optional root client ID of block list. * * @return {Object[]} Post blocks. */ @@ -224,7 +224,7 @@ export const getClientIdsWithDescendants = createSelector( * The number returned includes nested blocks. * * @param {Object} state Global application state. - * @param {?String} blockName Optional block name, if specified only blocks of that type will be counted. + * @param {?string} blockName Optional block name, if specified only blocks of that type will be counted. * * @return {number} Number of blocks in the post, or number of blocks with name equal to blockName. */ @@ -1297,6 +1297,7 @@ export const getInserterItems = createSelector( /** * Determines whether there are items to show in the inserter. + * * @param {Object} state Editor state. * @param {?string} rootClientId Optional root client ID of block list. * diff --git a/packages/block-editor/src/utils/transform-styles/ast/parse.js b/packages/block-editor/src/utils/transform-styles/ast/parse.js index 4f7e925c9937e1..b7c033fc3e72fe 100644 --- a/packages/block-editor/src/utils/transform-styles/ast/parse.js +++ b/packages/block-editor/src/utils/transform-styles/ast/parse.js @@ -11,15 +11,15 @@ export default function( css, options ) { options = options || {}; /** - * Positional. - */ + * Positional. + */ let lineno = 1; let column = 1; /** - * Update lineno and column based on `str`. - */ + * Update lineno and column based on `str`. + */ function updatePosition( str ) { const lines = str.match( /\n/g ); @@ -32,8 +32,8 @@ export default function( css, options ) { } /** - * Mark position and patch `node.position`. - */ + * Mark position and patch `node.position`. + */ function position() { const start = { line: lineno, column }; @@ -45,8 +45,8 @@ export default function( css, options ) { } /** - * Store position information for a node - */ + * Store position information for a node + */ function Position( start ) { this.start = start; @@ -55,14 +55,14 @@ export default function( css, options ) { } /** - * Non-enumerable source string - */ + * Non-enumerable source string + */ Position.prototype.content = css; /** - * Error `msg`. - */ + * Error `msg`. + */ const errorsList = []; @@ -82,8 +82,8 @@ export default function( css, options ) { } /** - * Parse stylesheet. - */ + * Parse stylesheet. + */ function stylesheet() { const rulesList = rules(); @@ -99,24 +99,24 @@ export default function( css, options ) { } /** - * Opening brace. - */ + * Opening brace. + */ function open() { return match( /^{\s*/ ); } /** - * Closing brace. - */ + * Closing brace. + */ function close() { return match( /^}/ ); } /** - * Parse ruleset. - */ + * Parse ruleset. + */ function rules() { let node; @@ -133,8 +133,8 @@ export default function( css, options ) { } /** - * Match `re` and return captures. - */ + * Match `re` and return captures. + */ function match( re ) { const m = re.exec( css ); @@ -148,16 +148,16 @@ export default function( css, options ) { } /** - * Parse whitespace. - */ + * Parse whitespace. + */ function whitespace() { match( /^\s*/ ); } /** - * Parse comments; - */ + * Parse comments; + */ function comments( accumulator ) { let c; @@ -172,8 +172,8 @@ export default function( css, options ) { } /** - * Parse comment. - */ + * Parse comment. + */ function comment() { const pos = position(); @@ -204,16 +204,15 @@ export default function( css, options ) { } /** - * Parse selector. - */ + * Parse selector. + */ function selector() { const m = match( /^([^{]+)/ ); if ( ! m ) { return; } - /* @fix Remove all comments from selectors - * http://ostermiller.org/findcomment.html */ + // FIXME: Remove all comments from selectors http://ostermiller.org/findcomment.html return trim( m[ 0 ] ) .replace( /\/\*([^*]|[\r\n]|(\*+([^*/]|[\r\n])))*\*\/+/g, '' ) .replace( /"(?:\\"|[^"])*"|'(?:\\'|[^'])*'/g, function( matched ) { @@ -226,8 +225,8 @@ export default function( css, options ) { } /** - * Parse declaration. - */ + * Parse declaration. + */ function declaration() { const pos = position(); @@ -260,8 +259,8 @@ export default function( css, options ) { } /** - * Parse declarations. - */ + * Parse declarations. + */ function declarations() { const decls = []; @@ -288,8 +287,8 @@ export default function( css, options ) { } /** - * Parse keyframe. - */ + * Parse keyframe. + */ function keyframe() { let m; @@ -314,8 +313,8 @@ export default function( css, options ) { } /** - * Parse keyframes. - */ + * Parse keyframes. + */ function atkeyframes() { const pos = position(); @@ -358,8 +357,8 @@ export default function( css, options ) { } /** - * Parse supports. - */ + * Parse supports. + */ function atsupports() { const pos = position(); @@ -388,8 +387,8 @@ export default function( css, options ) { } /** - * Parse host. - */ + * Parse host. + */ function athost() { const pos = position(); @@ -416,8 +415,8 @@ export default function( css, options ) { } /** - * Parse media. - */ + * Parse media. + */ function atmedia() { const pos = position(); @@ -446,8 +445,8 @@ export default function( css, options ) { } /** - * Parse custom-media. - */ + * Parse custom-media. + */ function atcustommedia() { const pos = position(); @@ -464,8 +463,8 @@ export default function( css, options ) { } /** - * Parse paged media. - */ + * Parse paged media. + */ function atpage() { const pos = position(); @@ -501,8 +500,8 @@ export default function( css, options ) { } /** - * Parse document. - */ + * Parse document. + */ function atdocument() { const pos = position(); @@ -533,8 +532,8 @@ export default function( css, options ) { } /** - * Parse font-face. - */ + * Parse font-face. + */ function atfontface() { const pos = position(); @@ -567,26 +566,26 @@ export default function( css, options ) { } /** - * Parse import - */ + * Parse import + */ const atimport = _compileAtrule( 'import' ); /** - * Parse charset - */ + * Parse charset + */ const atcharset = _compileAtrule( 'charset' ); /** - * Parse namespace - */ + * Parse namespace + */ const atnamespace = _compileAtrule( 'namespace' ); /** - * Parse non-block at-rules - */ + * Parse non-block at-rules + */ function _compileAtrule( name ) { const re = new RegExp( '^@' + name + '\\s*([^;]+);' ); @@ -603,8 +602,8 @@ export default function( css, options ) { } /** - * Parse at rule. - */ + * Parse at rule. + */ function atrule() { if ( css[ 0 ] !== '@' ) { @@ -625,8 +624,8 @@ export default function( css, options ) { } /** - * Parse rule. - */ + * Parse rule. + */ function rule() { const pos = position(); diff --git a/packages/block-editor/src/utils/transform-styles/ast/stringify/compiler.js b/packages/block-editor/src/utils/transform-styles/ast/stringify/compiler.js index fb17a2f15e9ddb..1835dd6392583f 100644 --- a/packages/block-editor/src/utils/transform-styles/ast/stringify/compiler.js +++ b/packages/block-editor/src/utils/transform-styles/ast/stringify/compiler.js @@ -9,10 +9,6 @@ export default Compiler; /** * Initialize a compiler. - * - * @param {Type} name - * @return {Type} - * @api public */ function Compiler( opts ) { diff --git a/packages/block-editor/src/utils/transform-styles/ast/stringify/index.js b/packages/block-editor/src/utils/transform-styles/ast/stringify/index.js index 9a5b995f059b0a..2dcc4d4475f02b 100644 --- a/packages/block-editor/src/utils/transform-styles/ast/stringify/index.js +++ b/packages/block-editor/src/utils/transform-styles/ast/stringify/index.js @@ -17,8 +17,7 @@ import Identity from './identity'; * * @param {Object} node * @param {Object} [options] - * @return {String} - * @api public + * @return {string} */ export default function( node, options ) { 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 5f454bd29ef3d4..4516fffa2196dc 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 @@ -55,7 +55,6 @@ function isValidURL( meta ) { * * @param {string} str the url * @param {string} baseURL base URL - * @param {string} absolutePath the absolute path * * @return {string} the full path to the file */ diff --git a/packages/block-editor/src/utils/transform-styles/transforms/wrap.js b/packages/block-editor/src/utils/transform-styles/transforms/wrap.js index 6c89562d78a9ae..d7fe709138fa83 100644 --- a/packages/block-editor/src/utils/transform-styles/transforms/wrap.js +++ b/packages/block-editor/src/utils/transform-styles/transforms/wrap.js @@ -4,7 +4,7 @@ import { includes } from 'lodash'; /** - * @const string IS_ROOT_TAG Regex to check if the selector is a root tag selector. + * @constant string IS_ROOT_TAG Regex to check if the selector is a root tag selector. */ const IS_ROOT_TAG = /^(body|html|:root).*$/; diff --git a/packages/block-library/src/columns/edit.js b/packages/block-library/src/columns/edit.js index d798f9f2115cb6..48f35e90b2d9ce 100644 --- a/packages/block-library/src/columns/edit.js +++ b/packages/block-library/src/columns/edit.js @@ -43,7 +43,7 @@ import { * * @constant * @type {string[]} -*/ + */ const ALLOWED_BLOCKS = [ 'core/column' ]; /** @@ -101,7 +101,7 @@ const TEMPLATE_OPTIONS = [ * Number of columns to assume for template in case the user opts to skip * template option selection. * - * @type {Number} + * @type {number} */ const DEFAULT_COLUMNS = 2; diff --git a/packages/block-library/src/embed/util.js b/packages/block-library/src/embed/util.js index 80bcbed310e9a0..04c66a4ff00ecc 100644 --- a/packages/block-library/src/embed/util.js +++ b/packages/block-library/src/embed/util.js @@ -58,7 +58,7 @@ export const getPhotoHtml = ( photo ) => { return renderToString( photoPreview ); }; -/*** +/** * Creates a more suitable embed block based on the passed in props * and attributes generated from an embed block's preview. * @@ -68,8 +68,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 = ( props, attributesFromPreview ) => { @@ -175,7 +175,7 @@ export function getClassNames( html, existingClassNames = '', allowResponsive = * Creates a paragraph block containing a link to the URL, and calls `onReplace`. * * @param {string} url The URL that could not be embedded. - * @param {function} onReplace Function to call with the created fallback block. + * @param {Function} onReplace Function to call with the created fallback block. */ export function fallback( url, onReplace ) { const link = { url }; diff --git a/packages/block-library/src/table/edit.js b/packages/block-library/src/table/edit.js index 6c44a305a9375a..b86c0e282d7f9b 100644 --- a/packages/block-library/src/table/edit.js +++ b/packages/block-library/src/table/edit.js @@ -423,6 +423,7 @@ export class TableEdit extends Component { /** * Renders a table section. * + * @param {Object} options * @param {string} options.type Section type: head, body, or foot. * @param {Array} options.rows The rows to render. * diff --git a/packages/block-library/src/table/state.js b/packages/block-library/src/table/state.js index 89fd1c0227ef35..f8ee18d7f2390b 100644 --- a/packages/block-library/src/table/state.js +++ b/packages/block-library/src/table/state.js @@ -8,6 +8,7 @@ const INHERITED_COLUMN_ATTRIBUTES = [ 'align' ]; /** * Creates a table state. * + * @param {Object} options * @param {number} options.rowCount Row count for the table to create. * @param {number} options.columnCount Column count for the table to create. * @@ -141,6 +142,7 @@ export function isCellSelected( cellLocation, selection ) { * Inserts a row in the table state. * * @param {Object} state Current table state. + * @param {Object} options * @param {string} options.sectionName Section in which to insert the row. * @param {number} options.rowIndex Row index at which to insert the row. * @@ -183,6 +185,7 @@ export function insertRow( state, { * Deletes a row from the table state. * * @param {Object} state Current table state. + * @param {Object} options * @param {string} options.sectionName Section in which to delete the row. * @param {number} options.rowIndex Row index to delete. * @@ -201,6 +204,7 @@ export function deleteRow( state, { * Inserts a column in the table state. * * @param {Object} state Current table state. + * @param {Object} options * @param {number} options.columnIndex Column index at which to insert the column. * * @return {Object} New table state. @@ -241,6 +245,7 @@ export function insertColumn( state, { * Deletes a column from the table state. * * @param {Object} state Current table state. + * @param {Object} options * @param {number} options.columnIndex Column index to delete. * * @return {Object} New table state. diff --git a/packages/block-serialization-default-parser/src/index.js b/packages/block-serialization-default-parser/src/index.js index e885e57af6269e..d92fcfc5fc18bb 100644 --- a/packages/block-serialization-default-parser/src/index.js +++ b/packages/block-serialization-default-parser/src/index.js @@ -32,9 +32,9 @@ let stack; * not captured. thus, we find the long string of `a`s and remember it, then * reference it as a whole unit inside our pattern * - * @cite http://instanceof.me/post/52245507631/regex-emulate-atomic-grouping-with-lookahead - * @cite http://blog.stevenlevithan.com/archives/mimic-atomic-groups - * @cite https://javascript.info/regexp-infinite-backtracking-problem + * @see http://instanceof.me/post/52245507631/regex-emulate-atomic-grouping-with-lookahead + * @see http://blog.stevenlevithan.com/archives/mimic-atomic-groups + * @see https://javascript.info/regexp-infinite-backtracking-problem * * once browsers reliably support atomic grouping or possessive * quantifiers natively we should remove this trick and simplify diff --git a/packages/blocks/README.md b/packages/blocks/README.md index 331be71c3a15f4..26e4ad5624edff 100644 --- a/packages/blocks/README.md +++ b/packages/blocks/README.md @@ -586,6 +586,7 @@ Converts an HTML string to known blocks. Strips everything else. _Parameters_ +- _options_ `Object`: - _options.HTML_ `[string]`: The HTML to convert. - _options.plainText_ `[string]`: Plain text version. - _options.mode_ `[string]`: 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. @@ -602,6 +603,7 @@ Converts an HTML string to known blocks. _Parameters_ +- _$1_ `Object`: - _$1.HTML_ `string`: The HTML to convert. _Returns_ diff --git a/packages/blocks/src/api/raw-handling/image-corrector.native.js b/packages/blocks/src/api/raw-handling/image-corrector.native.js index d450ac7441730c..f25f6d3c8bc903 100644 --- a/packages/blocks/src/api/raw-handling/image-corrector.native.js +++ b/packages/blocks/src/api/raw-handling/image-corrector.native.js @@ -5,7 +5,7 @@ * @param {Node} node The node to check. * * @return {void} -*/ + */ export default function( node ) { if ( node.nodeName !== 'IMG' ) { return; diff --git a/packages/blocks/src/api/raw-handling/index.js b/packages/blocks/src/api/raw-handling/index.js index 58044375d9dc31..37908f96d7d76a 100644 --- a/packages/blocks/src/api/raw-handling/index.js +++ b/packages/blocks/src/api/raw-handling/index.js @@ -81,6 +81,7 @@ function htmlToBlocks( { html, rawTransforms } ) { /** * Converts an HTML string to known blocks. * + * @param {Object} $1 * @param {string} $1.HTML The HTML to convert. * * @return {Array} A list of blocks. diff --git a/packages/blocks/src/api/raw-handling/paste-handler.js b/packages/blocks/src/api/raw-handling/paste-handler.js index c99b4ea5c5d0a2..fdea17bd0eba2f 100644 --- a/packages/blocks/src/api/raw-handling/paste-handler.js +++ b/packages/blocks/src/api/raw-handling/paste-handler.js @@ -113,6 +113,7 @@ function htmlToBlocks( { html, rawTransforms } ) { /** * Converts an HTML string to known blocks. Strips everything else. * + * @param {Object} options * @param {string} [options.HTML] The HTML to convert. * @param {string} [options.plainText] Plain text version. * @param {string} [options.mode] Handle content as blocks or inline content. diff --git a/packages/blocks/src/api/registration.js b/packages/blocks/src/api/registration.js index b88eec96ecac7e..024f9e9d55a3e3 100644 --- a/packages/blocks/src/api/registration.js +++ b/packages/blocks/src/api/registration.js @@ -36,7 +36,7 @@ import { DEPRECATED_ENTRY_KEYS } from './constants'; /** * An object describing a normalized block type icon. * - * @typedef {WPBlockTypeIconDescriptor} + * @typedef {Object} WPBlockTypeIconDescriptor * * @property {WPBlockTypeIconRender} src Render behavior of the icon, * one of a Dashicon slug, an @@ -60,23 +60,23 @@ import { DEPRECATED_ENTRY_KEYS } from './constants'; /** * Defined behavior of a block type. * - * @typedef {WPBlockType} - * - * @property {string} name Block type's namespaced name. - * @property {string} title Human-readable block type label. - * @property {string} category Block type category classification, - * used in search interfaces to arrange - * block types by category. - * @property {?WPBlockTypeIcon} icon Block type icon. - * @property {?string[]} keywords Additional keywords to produce block - * type as result in search interfaces. - * @property {?Object} attributes Block type attributes. - * @property {?WPComponent} save Optional component describing - * serialized markup structure of a - * block type. - * @property {WPComponent} edit Component rendering an element to - * manipulate the attributes of a block - * in the context of an editor. + * @typedef {Object} WPBlockType + * + * @property {string} name Block type's namespaced name. + * @property {string} title Human-readable block type label. + * @property {string} category Block type category classification, + * used in search interfaces to arrange + * block types by category. + * @property {WPBlockTypeIcon} [icon] Block type icon. + * @property {string[]} [keywords] Additional keywords to produce block + * type as result in search interfaces. + * @property {Object} [attributes] Block type attributes. + * @property {WPComponent} [save] Optional component describing + * serialized markup structure of a + * block type. + * @property {WPComponent} edit Component rendering an element to + * manipulate the attributes of a block + * in the context of an editor. */ /** diff --git a/packages/blocks/src/store/reducer.js b/packages/blocks/src/store/reducer.js index 4e3131ca7b62e0..405e60109adda3 100644 --- a/packages/blocks/src/store/reducer.js +++ b/packages/blocks/src/store/reducer.js @@ -102,7 +102,7 @@ export function blockStyles( state = {}, action ) { * * @param {string} setActionType Action type. * - * @return {function} Reducer. + * @return {Function} Reducer. */ export function createBlockNameSetterReducer( setActionType ) { return ( state = null, action ) => { diff --git a/packages/components/src/autocomplete/index.js b/packages/components/src/autocomplete/index.js index 1226ec3bbfd7fe..0ae8e2b80bdb90 100644 --- a/packages/components/src/autocomplete/index.js +++ b/packages/components/src/autocomplete/index.js @@ -30,34 +30,35 @@ import withSpokenMessages from '../higher-order/with-spoken-messages'; /** * A raw completer option. + * * @typedef {*} CompleterOption */ /** * @callback FnGetOptions * - * @returns {(CompleterOption[]|Promise.)} The completer options or a promise for them. + * @return {(CompleterOption[]|Promise.)} The completer options or a promise for them. */ /** * @callback FnGetOptionKeywords * @param {CompleterOption} option a completer option. * - * @returns {string[]} list of key words to search. + * @return {string[]} list of key words to search. */ /** * @callback FnIsOptionDisabled * @param {CompleterOption} option a completer option. * - * @returns {string[]} whether or not the given option is disabled. + * @return {string[]} whether or not the given option is disabled. */ /** * @callback FnGetOptionLabel * @param {CompleterOption} option a completer option. * - * @returns {(string|Array.<(string|Component)>)} list of react components to render. + * @return {(string|Array.<(string|Component)>)} list of react components to render. */ /** @@ -65,35 +66,36 @@ import withSpokenMessages from '../higher-order/with-spoken-messages'; * @param {string} before the string before the auto complete trigger and query. * @param {string} after the string after the autocomplete trigger and query. * - * @returns {boolean} true if the completer can handle. + * @return {boolean} true if the completer can handle. */ /** * @typedef {Object} OptionCompletion - * @property {('insert-at-caret', 'replace')} action the intended placement of the completion. + * @property {'insert-at-caret'|'replace'} action the intended placement of the completion. * @property {OptionCompletionValue} value the completion value. */ /** * A completion value. - * @typedef {(String|WPElement|Object)} OptionCompletionValue + * + * @typedef {(string|WPElement|Object)} OptionCompletionValue */ /** * @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. * - * @returns {(OptionCompletion|OptionCompletionValue)} the completion for the given option. If an + * @return {(OptionCompletion|OptionCompletionValue)} the completion for the given option. If an * OptionCompletionValue is returned, the * completion action defaults to `insert-at-caret`. */ /** * @typedef {Object} Completer - * @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 {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. diff --git a/packages/components/src/color-picker/index.js b/packages/components/src/color-picker/index.js index 3db7096c2e3d96..74c42f3cee8f8e 100644 --- a/packages/components/src/color-picker/index.js +++ b/packages/components/src/color-picker/index.js @@ -85,7 +85,7 @@ const isValidColor = ( colors ) => colors.hex ? * @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|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`. diff --git a/packages/components/src/draggable/index.js b/packages/components/src/draggable/index.js index f0bc9bbc71a40e..ac077468d83777 100644 --- a/packages/components/src/draggable/index.js +++ b/packages/components/src/draggable/index.js @@ -66,8 +66,6 @@ class Draggable extends Component { * - Adds dragover listener. * * @param {Object} event The non-custom DragEvent. - * @param {string} elementId The HTML id of the element to be dragged. - * @param {Object} transferData The data to be set to the event's dataTransfer - to be accessible in any later drop logic. */ onDragStart( event ) { const { elementId, transferData, onDragStart = noop } = this.props; diff --git a/packages/components/src/higher-order/with-notices/index.js b/packages/components/src/higher-order/with-notices/index.js index bcdb43b1a2e876..49a44608039ce1 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 {function|Component} OriginalComponent Original component. + * @param {Function|Component} OriginalComponent Original component. * @return {Component} Wrapped component. */ export default createHigherOrderComponent( ( OriginalComponent ) => { @@ -43,10 +43,10 @@ export default createHigherOrderComponent( ( OriginalComponent ) => { } /** - * Function passed down as a prop that adds a new notice. - * - * @param {Object} notice Notice to add. - */ + * Function passed down as a prop that adds a new notice. + * + * @param {Object} notice Notice to add. + */ createNotice( notice ) { const noticeToAdd = notice.id ? notice : { ...notice, id: uuid() }; this.setState( ( state ) => ( { @@ -55,19 +55,19 @@ export default createHigherOrderComponent( ( OriginalComponent ) => { } /** - * Function passed as a prop that adds a new error notice. - * - * @param {string} msg Error message of the notice. - */ + * Function passed as a prop that adds a new error notice. + * + * @param {string} msg Error message of the notice. + */ createErrorNotice( msg ) { this.createNotice( { status: 'error', content: msg } ); } /** - * Removes a notice by id. - * - * @param {string} id Id of the notice to remove. - */ + * Removes a notice by id. + * + * @param {string} id Id of the notice to remove. + */ removeNotice( id ) { this.setState( ( state ) => ( { noticeList: state.noticeList.filter( ( notice ) => notice.id !== id ), @@ -75,8 +75,8 @@ export default createHigherOrderComponent( ( OriginalComponent ) => { } /** - * Removes all notices - */ + * Removes all notices + */ removeAllNotices() { this.setState( { noticeList: [], diff --git a/packages/components/src/notice/list.js b/packages/components/src/notice/list.js index dcb39dc49b5828..64c68cbaede0e3 100644 --- a/packages/components/src/notice/list.js +++ b/packages/components/src/notice/list.js @@ -10,15 +10,15 @@ import { noop, omit } from 'lodash'; 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. -*/ + * 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. + */ function NoticeList( { notices, onRemove = noop, className, children } ) { const removeNotice = ( id ) => () => onRemove( id ); diff --git a/packages/components/src/placeholder/index.js b/packages/components/src/placeholder/index.js index 8e49b70d5226ec..3a7c40c993001f 100644 --- a/packages/components/src/placeholder/index.js +++ b/packages/components/src/placeholder/index.js @@ -10,11 +10,11 @@ import { isString } from 'lodash'; import Dashicon from '../dashicon'; /** -* Renders a placeholder. Normally used by blocks to render their empty state. -* -* @param {Object} props The component props. -* @return {Object} The rendered placeholder. -*/ + * Renders a placeholder. Normally used by blocks to render their empty state. + * + * @param {Object} props The component props. + * @return {Object} The rendered placeholder. + */ function Placeholder( { icon, children, label, instructions, className, notices, preview, isColumnLayout, ...additionalProps } ) { const classes = classnames( 'components-placeholder', className ); const fieldsetClasses = classnames( 'components-placeholder__fieldset', { 'is-column-layout': isColumnLayout } ); diff --git a/packages/components/src/popover/index.js b/packages/components/src/popover/index.js index 1dad7be985dfb5..a6aff279f0b151 100644 --- a/packages/components/src/popover/index.js +++ b/packages/components/src/popover/index.js @@ -30,14 +30,14 @@ const FocusManaged = withConstrainedTabbing( withFocusReturn( ( { children } ) = /** * Name of slot in which popover should fill. * - * @type {String} + * @type {string} */ const SLOT_NAME = 'Popover'; /** * Hook used trigger an event handler once the window is resized or scrolled. * - * @param {function} handler Event handler. + * @param {Function} handler Event handler. * @param {Object} ignoredScrollalbeRef scroll events inside this element are ignored. */ function useThrottledWindowScrollOrResize( handler, ignoredScrollalbeRef ) { diff --git a/packages/components/src/popover/utils.js b/packages/components/src/popover/utils.js index 292f7ab3276775..1b71fab09aa574 100644 --- a/packages/components/src/popover/utils.js +++ b/packages/components/src/popover/utils.js @@ -13,7 +13,6 @@ const isRTL = () => document.documentElement.dir === 'rtl'; * @param {Object} contentSize Content Size. * @param {string} xAxis Desired xAxis. * @param {string} chosenYAxis yAxis to be used. - * @param {boolean} expandOnMobile Whether to expand the popover on mobile or not. * * @return {Object} Popover xAxis position and constraints. */ @@ -83,7 +82,6 @@ export function computePopoverXAxisPosition( anchorRect, contentSize, xAxis, cho * @param {Object} anchorRect Anchor Rect. * @param {Object} contentSize Content Size. * @param {string} yAxis Desired yAxis. - * @param {boolean} expandOnMobile Whether to expand the popover on mobile or not. * * @return {Object} Popover xAxis position and constraints. */ diff --git a/packages/components/src/snackbar/list.js b/packages/components/src/snackbar/list.js index ca9060560ad0a2..f3cb5d544fcad5 100644 --- a/packages/components/src/snackbar/list.js +++ b/packages/components/src/snackbar/list.js @@ -17,15 +17,15 @@ import { useState } from '@wordpress/element'; 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. -*/ + * 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. + */ function SnackbarList( { notices, className, children, onRemove = noop } ) { const isReducedMotion = useReducedMotion(); const [ refMap ] = useState( () => new WeakMap() ); diff --git a/packages/components/src/toolbar/index.js b/packages/components/src/toolbar/index.js index 3dc1f3c1d4451a..ca41d32bb6e1b9 100644 --- a/packages/components/src/toolbar/index.js +++ b/packages/components/src/toolbar/index.js @@ -34,10 +34,11 @@ import ToolbarContainer from './toolbar-container'; * Either `controls` or `children` is required, otherwise this components * renders nothing. * - * @param {?Array} controls The controls to render in this toolbar. - * @param {?ReactElement} children Any other things to render inside the - * toolbar besides the controls. - * @param {?string} className Class to set on the container div. + * @param {Object} props + * @param {Array} [props.controls] The controls to render in this toolbar. + * @param {ReactElement} [props.children] Any other things to render inside the + * toolbar besides the controls. + * @param {string} [props.className] Class to set on the container div. * * @return {ReactElement} The rendered toolbar. */ diff --git a/packages/components/src/tooltip/index.js b/packages/components/src/tooltip/index.js index 9c7d0acb800ad6..fd52b17ca487df 100644 --- a/packages/components/src/tooltip/index.js +++ b/packages/components/src/tooltip/index.js @@ -22,7 +22,7 @@ import Shortcut from '../shortcut'; /** * Time over children to wait before showing tooltip * - * @type {Number} + * @type {number} */ const TOOLTIP_DELAY = 700; diff --git a/packages/core-data/src/controls.js b/packages/core-data/src/controls.js index 6df3d092094f8b..84644e76541ac9 100644 --- a/packages/core-data/src/controls.js +++ b/packages/core-data/src/controls.js @@ -19,6 +19,7 @@ export function apiFetch( request ) { /** * Calls a selector using the current state. + * * @param {string} selectorName Selector name. * @param {Array} args Selector arguments. * diff --git a/packages/core-data/src/queried-data/get-query-parts.js b/packages/core-data/src/queried-data/get-query-parts.js index d13490e42a72f5..de8a5311619ddd 100644 --- a/packages/core-data/src/queried-data/get-query-parts.js +++ b/packages/core-data/src/queried-data/get-query-parts.js @@ -11,7 +11,7 @@ import { withWeakMapCache } from '../utils'; /** * An object of properties describing a specific query. * - * @typedef {WPQueriedDataQueryParts} + * @typedef {Object} WPQueriedDataQueryParts * * @property {number} page The query page (1-based index, default 1). * @property {number} perPage Items per page for query (default 10). diff --git a/packages/data-controls/src/index.js b/packages/data-controls/src/index.js index c209b3397b4fad..27dc772545bbca 100644 --- a/packages/data-controls/src/index.js +++ b/packages/data-controls/src/index.js @@ -95,10 +95,11 @@ export function dispatch( storeKey, actionName, ...args ) { /** * Utility for returning a promise that handles a selector with a resolver. * - * @param {Object} registry The data registry. - * @param {string} storeKey The store the selector belongs to - * @param {string} selectorName The selector name - * @param {Array} args The arguments fed to the selector + * @param {Object} registry The data registry. + * @param {Object} options + * @param {string} options.storeKey The store the selector belongs to + * @param {string} options.selectorName The selector name + * @param {Array} options.args The arguments fed to the selector * * @return {Promise} A promise for resolving the given selector. */ diff --git a/packages/data/README.md b/packages/data/README.md index 0e117eca77d876..a76019371e725a 100644 --- a/packages/data/README.md +++ b/packages/data/README.md @@ -312,11 +312,11 @@ Mark a control as a registry control. _Parameters_ -- _registryControl_ `function`: Function receiving a registry object and returning a control. +- _registryControl_ `Function`: Function receiving a registry object and returning a control. _Returns_ -- `function`: marked registry control. +- `Function`: marked registry control. # **createRegistrySelector** @@ -324,11 +324,11 @@ Mark a selector as a registry selector. _Parameters_ -- _registrySelector_ `function`: Function receiving a registry object and returning a state selector. +- _registrySelector_ `Function`: Function receiving a registry object and returning a state selector. _Returns_ -- `function`: marked registry selector. +- `Function`: marked registry selector. # **dispatch** diff --git a/packages/data/src/factory.js b/packages/data/src/factory.js index 26fceb9bd456d5..2a10c7a8e7afc1 100644 --- a/packages/data/src/factory.js +++ b/packages/data/src/factory.js @@ -10,9 +10,9 @@ import defaultRegistry from './default-registry'; /** * Mark a selector as a registry selector. * - * @param {function} registrySelector Function receiving a registry object and returning a state selector. + * @param {Function} registrySelector Function receiving a registry object and returning a state selector. * - * @return {function} marked registry selector. + * @return {Function} marked registry selector. */ export function createRegistrySelector( registrySelector ) { const selector = ( ...args ) => registrySelector( selector.registry.select )( ...args ); @@ -39,9 +39,9 @@ export function createRegistrySelector( registrySelector ) { /** * Mark a control as a registry control. * - * @param {function} registryControl Function receiving a registry object and returning a control. + * @param {Function} registryControl Function receiving a registry object and returning a control. * - * @return {function} marked registry control. + * @return {Function} marked registry control. */ export function createRegistryControl( registryControl ) { registryControl.isRegistryControl = true; diff --git a/packages/data/src/index.js b/packages/data/src/index.js index da00faec053d41..8dd6893c5d9e01 100644 --- a/packages/data/src/index.js +++ b/packages/data/src/index.js @@ -133,11 +133,11 @@ export const dispatch = defaultRegistry.dispatch; export const subscribe = defaultRegistry.subscribe; /** -* Registers a generic store. -* -* @param {string} key Store registry key. -* @param {Object} config Configuration (getSelectors, getActions, subscribe). -*/ + * Registers a generic store. + * + * @param {string} key Store registry key. + * @param {Object} config Configuration (getSelectors, getActions, subscribe). + */ export const registerGenericStore = defaultRegistry.registerGenericStore; /** diff --git a/packages/data/src/namespace-store/metadata/reducer.js b/packages/data/src/namespace-store/metadata/reducer.js index 46ddc183563ae0..17d271ec9d365d 100644 --- a/packages/data/src/namespace-store/metadata/reducer.js +++ b/packages/data/src/namespace-store/metadata/reducer.js @@ -18,7 +18,7 @@ import { onSubKey } from './utils'; * @param {Object} state Current state. * @param {Object} action Dispatched action. * - * @returns {Object} Next state. + * @return {Object} Next state. */ const subKeysIsResolved = flowRight( [ onSubKey( 'selectorName' ), diff --git a/packages/data/src/plugins/persistence/index.js b/packages/data/src/plugins/persistence/index.js index a21fcb9b442fe2..a0c910f8a73bca 100644 --- a/packages/data/src/plugins/persistence/index.js +++ b/packages/data/src/plugins/persistence/index.js @@ -10,14 +10,13 @@ import defaultStorage from './storage/default'; import { combineReducers } from '../../'; /** - * Persistence plugin options. + * @typedef {Object} WPDataPersistencePluginOptions Persistence plugin options. * * @property {Storage} storage Persistent storage implementation. This must * at least implement `getItem` and `setItem` of * the Web Storage API. * @property {string} storageKey Key on which to set in persistent storage. * - * @typedef {WPDataPersistencePluginOptions} */ /** diff --git a/packages/data/src/promise-middleware.js b/packages/data/src/promise-middleware.js index 832ecbaefdf187..16cd4ccf097443 100644 --- a/packages/data/src/promise-middleware.js +++ b/packages/data/src/promise-middleware.js @@ -6,7 +6,7 @@ import isPromise from 'is-promise'; /** * Simplest possible promise redux middleware. * - * @return {function} middleware. + * @return {Function} middleware. */ const promiseMiddleware = () => ( next ) => ( action ) => { if ( isPromise( action ) ) { diff --git a/packages/data/src/registry.js b/packages/data/src/registry.js index 97e5212f2a24ab..ecaaa94c8e64d5 100644 --- a/packages/data/src/registry.js +++ b/packages/data/src/registry.js @@ -13,9 +13,7 @@ import createNamespace from './namespace-store'; import createCoreDataStore from './store'; /** - * An isolated orchestrator of store registrations. - * - * @typedef {Object} WPDataRegistry + * @typedef {Object} WPDataRegistry An isolated orchestrator of store registrations. * * @property {Function} registerGenericStore Given a namespace key and settings * object, registers a new generic @@ -35,9 +33,7 @@ import createCoreDataStore from './store'; */ /** - * An object of registry function overrides. - * - * @typedef {WPDataPlugin} + * @typedef {Object} WPDataPlugin An object of registry function overrides. */ /** diff --git a/packages/date/src/index.js b/packages/date/src/index.js index 26501b394200b6..14aa677d2e4218 100644 --- a/packages/date/src/index.js +++ b/packages/date/src/index.js @@ -105,19 +105,19 @@ function setupWPTimezone() { /** * Number of seconds in one minute. * - * @type {Number} + * @type {number} */ const MINUTE_IN_SECONDS = 60; /** * Number of minutes in one hour. * - * @type {Number} + * @type {number} */ const HOUR_IN_MINUTES = 60; /** * Number of seconds in one hour. * - * @type {Number} + * @type {number} */ const HOUR_IN_SECONDS = 60 * MINUTE_IN_SECONDS; diff --git a/packages/dependency-extraction-webpack-plugin/util.js b/packages/dependency-extraction-webpack-plugin/util.js index b8b7238fe2a9a1..88db5088e3b88f 100644 --- a/packages/dependency-extraction-webpack-plugin/util.js +++ b/packages/dependency-extraction-webpack-plugin/util.js @@ -4,8 +4,9 @@ const WORDPRESS_NAMESPACE = '@wordpress/'; * Default request to global transformation * * Transform @wordpress dependencies: - * @wordpress/api-fetch -> wp.apiFetch - * @wordpress/i18n -> wp.i18n + * + * request `@wordpress/api-fetch` becomes `wp.apiFetch` + * request `@wordpress/i18n` becomes `wp.i18n` * * @param {string} request Requested module * @@ -42,8 +43,9 @@ function defaultRequestToExternal( request ) { * Default request to WordPress script handle transformation * * Transform @wordpress dependencies: - * @wordpress/i18n -> wp-i18n - * @wordpress/escape-html -> wp-escape-html + * + * request `@wordpress/i18n` becomes `wp-i18n` + * request `@wordpress/escape-html` becomes `wp-escape-html` * * @param {string} request Requested module * diff --git a/packages/docgen/src/engine.js b/packages/docgen/src/engine.js index 0c01f94ef9b505..e2510af0517dad 100644 --- a/packages/docgen/src/engine.js +++ b/packages/docgen/src/engine.js @@ -1,12 +1,12 @@ /** -* External dependencies. -*/ + * External dependencies. + */ const espree = require( 'espree' ); const { flatten } = require( 'lodash' ); /** -* Internal dependencies. -*/ + * Internal dependencies. + */ const getIntermediateRepresentation = require( './get-intermediate-representation' ); const getAST = ( source ) => espree.parse( source, { diff --git a/packages/e2e-test-utils/README.md b/packages/e2e-test-utils/README.md index d8f14e5e6c343b..3ffdec9ab8359c 100644 --- a/packages/e2e-test-utils/README.md +++ b/packages/e2e-test-utils/README.md @@ -82,7 +82,7 @@ _Parameters_ _Returns_ -- `function`: Function that determines if a request is for the embed API, embedding a specific URL. +- `Function`: Function that determines if a request is for the embed API, embedding a specific URL. # **createJSONResponse** @@ -127,7 +127,7 @@ _Parameters_ _Returns_ -- `function`: Function that determines if a request's URL contains substring. +- `Function`: Function that determines if a request's URL contains substring. # **deactivatePlugin** @@ -307,9 +307,9 @@ deserialised JSON response for the request. _Parameters_ -- _mockCheck_ `function`: function that returns true if the request should be mocked. +- _mockCheck_ `Function`: function that returns true if the request should be mocked. - _mock_ `Object`: A mock object to wrap in a JSON response, if the request should be mocked. -- _responseObjectTransform_ `(function|undefined)`: An optional function that transforms the response's object before the response is used. +- _responseObjectTransform_ `(Function|undefined)`: An optional function that transforms the response's object before the response is used. _Returns_ diff --git a/packages/e2e-test-utils/src/are-pre-publish-checks-enabled.js b/packages/e2e-test-utils/src/are-pre-publish-checks-enabled.js index 3aab4928850edd..70c17503ceb5b2 100644 --- a/packages/e2e-test-utils/src/are-pre-publish-checks-enabled.js +++ b/packages/e2e-test-utils/src/are-pre-publish-checks-enabled.js @@ -5,6 +5,7 @@ import { wpDataSelect } from './wp-data-select'; /** * Verifies if publish checks are enabled. + * * @return {boolean} Boolean which represents the state of prepublish checks. */ export function arePrePublishChecksEnabled() { diff --git a/packages/e2e-test-utils/src/get-block-setting.js b/packages/e2e-test-utils/src/get-block-setting.js index 0b4bff9dd7e14a..e0adf27eaebedf 100644 --- a/packages/e2e-test-utils/src/get-block-setting.js +++ b/packages/e2e-test-utils/src/get-block-setting.js @@ -1,5 +1,6 @@ /** * Returns a string containing the block title associated with the provided block name. + * * @param {string} blockName Block name. * @param {string} setting Block setting e.g: title, attributes.... * 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 66e1b301cbe0f5..9673ea04706d4a 100644 --- a/packages/e2e-test-utils/src/mocks/create-embedding-matcher.js +++ b/packages/e2e-test-utils/src/mocks/create-embedding-matcher.js @@ -8,7 +8,7 @@ import { createURLMatcher } from './create-url-matcher'; * * @param {string} parameterName The query parameter to check. * @param {string} value The value to check for. - * @return {function} Function that determines if a request's query parameter is the specified value. + * @return {Function} Function that determines if a request's query parameter is the specified value. */ function parameterEquals( parameterName, value ) { return ( request ) => { @@ -25,7 +25,7 @@ function parameterEquals( parameterName, value ) { * Creates a function to determine if a request is embedding a certain URL. * * @param {string} url The URL to check against a request. - * @return {function} Function that determines if a request is for the embed API, embedding a specific URL. + * @return {Function} Function that determines if a request is for the embed API, embedding a specific URL. */ export function createEmbeddingMatcher( url ) { return ( request ) => diff --git a/packages/e2e-test-utils/src/mocks/create-url-matcher.js b/packages/e2e-test-utils/src/mocks/create-url-matcher.js index db299a78641330..77c28d129b298f 100644 --- a/packages/e2e-test-utils/src/mocks/create-url-matcher.js +++ b/packages/e2e-test-utils/src/mocks/create-url-matcher.js @@ -2,7 +2,7 @@ * Creates a function to determine if a request is calling a URL with the substring present. * * @param {string} substring The substring to check for. - * @return {function} Function that determines if a request's URL contains substring. + * @return {Function} Function that determines if a request's URL contains substring. */ export function createURLMatcher( substring ) { return ( request ) => -1 !== request.url().indexOf( substring ); 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 0f858aabe56ca5..12cf8af07b24d2 100644 --- a/packages/e2e-test-utils/src/mocks/mock-or-transform.js +++ b/packages/e2e-test-utils/src/mocks/mock-or-transform.js @@ -12,9 +12,9 @@ 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 {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. + * @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`. */ export function mockOrTransform( diff --git a/packages/e2e-test-utils/src/set-post-content.js b/packages/e2e-test-utils/src/set-post-content.js index 18e47c55820033..3e7611ba16c5af 100644 --- a/packages/e2e-test-utils/src/set-post-content.js +++ b/packages/e2e-test-utils/src/set-post-content.js @@ -1,5 +1,6 @@ /** * Sets code editor content + * * @param {string} content New code editor content. * * @return {Promise} Promise resolving with an array containing all blocks in the document. diff --git a/packages/e2e-test-utils/src/wp-data-select.js b/packages/e2e-test-utils/src/wp-data-select.js index fac2bebcb3c1cb..05b92b0a6dbbec 100644 --- a/packages/e2e-test-utils/src/wp-data-select.js +++ b/packages/e2e-test-utils/src/wp-data-select.js @@ -1,5 +1,6 @@ /** * Queries the WordPress data module. + * * @param {string} store Store to query e.g: core/editor, core/blocks... * @param {string} selector Selector to exectute e.g: getBlocks. * @param {...Object} parameters Parameters to pass to the selector. diff --git a/packages/edit-post/src/components/editor-initialization/utils.js b/packages/edit-post/src/components/editor-initialization/utils.js index 7dfd1ea08ed892..11935236c83440 100644 --- a/packages/edit-post/src/components/editor-initialization/utils.js +++ b/packages/edit-post/src/components/editor-initialization/utils.js @@ -2,11 +2,11 @@ * 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 {Function} selector Selector. + * @param {Function} listener Listener. * @param {boolean} initial Flags whether listener should be invoked on * initial call. - * @return {function} Listener creator. + * @return {Function} Listener creator. */ export const onChangeListener = ( selector, listener, initial = false ) => { let previousValue = selector(); diff --git a/packages/edit-post/src/store/actions.js b/packages/edit-post/src/store/actions.js index d771dc840d8049..c96343ccae6750 100644 --- a/packages/edit-post/src/store/actions.js +++ b/packages/edit-post/src/store/actions.js @@ -108,7 +108,7 @@ export function toggleEditorPanelEnabled( panelName ) { * @param {string} panelName A string that identifies the panel to open or close. * * @return {Object} Action object. -*/ + */ export function toggleEditorPanelOpened( panelName ) { return { type: 'TOGGLE_PANEL_OPENED', diff --git a/packages/edit-post/src/store/constants.js b/packages/edit-post/src/store/constants.js index 35acac0c5633a8..d3c02c71f312ee 100644 --- a/packages/edit-post/src/store/constants.js +++ b/packages/edit-post/src/store/constants.js @@ -1,17 +1,20 @@ /** * The identifier for the data store. + * * @type {string} */ export const STORE_KEY = 'core/edit-post'; /** * CSS selector string for the admin bar view post link anchor tag. + * * @type {string} */ export const VIEW_AS_LINK_SELECTOR = '#wp-admin-bar-view a'; /** * CSS selector string for the admin bar preview post link anchor tag. + * * @type {string} */ export const VIEW_AS_PREVIEW_LINK_SELECTOR = '#wp-admin-bar-preview a'; diff --git a/packages/edit-widgets/src/store/actions.js b/packages/edit-widgets/src/store/actions.js index e2bcfe6f69094c..bff01d883b4d82 100644 --- a/packages/edit-widgets/src/store/actions.js +++ b/packages/edit-widgets/src/store/actions.js @@ -15,7 +15,7 @@ const WIDGET_AREAS_SAVE_NOTICE_ID = 'WIDGET_AREAS_SAVE_NOTICE_ID'; /** * Yields an action object that setups the widget areas. * - * @yields {Object} Action object. + * @yield {Object} Action object. */ export function* setupWidgetAreas() { const widgetAreas = yield select( @@ -54,7 +54,7 @@ export function updateBlocksInWidgetArea( widgetAreaId, blocks = [] ) { /** * Action that performs the logic to save widget areas. * - * @yields {Object} Action object. + * @yield {Object} Action object. */ export function* saveWidgetAreas() { const widgetAreas = yield select( diff --git a/packages/edit-widgets/src/store/constants.js b/packages/edit-widgets/src/store/constants.js index 4968386ea38ea1..6850993d9863db 100644 --- a/packages/edit-widgets/src/store/constants.js +++ b/packages/edit-widgets/src/store/constants.js @@ -1,5 +1,6 @@ /** * Constant for the store module (or reducer) key. + * * @type {string} */ export const STORE_KEY = 'core/edit-widgets'; diff --git a/packages/editor/src/components/autocompleters/user.js b/packages/editor/src/components/autocompleters/user.js index 0ca90dad349675..e3965a33f28d6f 100644 --- a/packages/editor/src/components/autocompleters/user.js +++ b/packages/editor/src/components/autocompleters/user.js @@ -4,10 +4,10 @@ import apiFetch from '@wordpress/api-fetch'; /** -* A user mentions completer. -* -* @type {Completer} -*/ + * A user mentions completer. + * + * @type {Completer} + */ export default { name: 'users', className: 'editor-autocompleters__user', diff --git a/packages/editor/src/components/post-preview-button/index.js b/packages/editor/src/components/post-preview-button/index.js index b09f50b431269d..a715c0fd3da5aa 100644 --- a/packages/editor/src/components/post-preview-button/index.js +++ b/packages/editor/src/components/post-preview-button/index.js @@ -83,7 +83,7 @@ function writeInterstitialMessage( targetDocument ) { /** * Filters the interstitial message shown when generating previews. * - * @param {String} markup The preview interstitial markup. + * @param {string} markup The preview interstitial markup. */ markup = applyFilters( 'editor.PostPreview.interstitialMarkup', markup ); 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 9083ae0035c6a4..8096e4ccf7f8d9 100644 --- a/packages/editor/src/components/post-type-support-check/index.js +++ b/packages/editor/src/components/post-type-support-check/index.js @@ -12,7 +12,8 @@ import { withSelect } from '@wordpress/data'; * A component which renders its own children only if the current editor post * type supports one of the given `supportKeys` prop. * - * @param {?Object} props.postType Current post type. + * @param {Object} 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 diff --git a/packages/editor/src/store/actions.native.js b/packages/editor/src/store/actions.native.js index 3d638cbc2be2cf..51741ac9bc3b44 100644 --- a/packages/editor/src/store/actions.native.js +++ b/packages/editor/src/store/actions.native.js @@ -5,7 +5,7 @@ export * from './actions.js'; * Returns an action object that enables or disables post title selection. * * @param {boolean} [isSelected=true] Whether post title is currently selected. - + * * @return {Object} Action object. */ export function togglePostTitleSelection( isSelected = true ) { diff --git a/packages/editor/src/store/constants.js b/packages/editor/src/store/constants.js index 8b9645c8d83099..6d12c68cc2af66 100644 --- a/packages/editor/src/store/constants.js +++ b/packages/editor/src/store/constants.js @@ -10,6 +10,7 @@ export const EDIT_MERGE_PROPERTIES = new Set( [ /** * Constant for the store module (or reducer) key. + * * @type {string} */ export const STORE_KEY = 'core/editor'; diff --git a/packages/editor/src/store/reducer.js b/packages/editor/src/store/reducer.js index 6676b74dcbc395..ef6ad6fd798c07 100644 --- a/packages/editor/src/store/reducer.js +++ b/packages/editor/src/store/reducer.js @@ -126,7 +126,7 @@ export function shouldOverwriteState( action, previousAction ) { * @param {Object} state Current state. * @param {Object} action Dispatched action. * - * @returns {Object} Updated state. + * @return {Object} Updated state. */ export const editor = flow( [ combineReducers, diff --git a/packages/element/README.md b/packages/element/README.md index 052ea244540560..0b96812eacb539 100755 --- a/packages/element/README.md +++ b/packages/element/README.md @@ -234,7 +234,9 @@ aside from `children` are passed. _Parameters_ +- _props_ `Object`: - _props.children_ `string`: HTML to render. +- _props.props_ `Object`: Any additonal props to be set on the containing div. _Returns_ diff --git a/packages/element/src/raw-html.js b/packages/element/src/raw-html.js index d985c9376d4a26..2fa3618c417d88 100644 --- a/packages/element/src/raw-html.js +++ b/packages/element/src/raw-html.js @@ -9,7 +9,9 @@ import { createElement } from './react'; * To preserve additional props, a `div` wrapper _will_ be created if any props * aside from `children` are passed. * + * @param {Object} props * @param {string} props.children HTML to render. + * @param {Object} props.props Any additonal props to be set on the containing div. * * @return {WPElement} Dangerously-rendering element. */ diff --git a/packages/eslint-plugin/rules/gutenberg-phase.js b/packages/eslint-plugin/rules/gutenberg-phase.js index 98c7a4216a4f73..168ce1ff782d03 100644 --- a/packages/eslint-plugin/rules/gutenberg-phase.js +++ b/packages/eslint-plugin/rules/gutenberg-phase.js @@ -3,7 +3,7 @@ * the predicate returns a truthy value for. * * @param {Object} sourceNode The AST node to search from. - * @param {function} predicate A predicate invoked for each parent. + * @param {Function} predicate A predicate invoked for each parent. * * @return {?Object } The first encountered parent node where the predicate * returns a truthy value. diff --git a/packages/format-library/src/link/utils.js b/packages/format-library/src/link/utils.js index d9115cbcfe0996..58f64ab71ce41b 100644 --- a/packages/format-library/src/link/utils.js +++ b/packages/format-library/src/link/utils.js @@ -83,9 +83,10 @@ export function isValidHref( href ) { /** * Generates the format object that will be applied to the link text. * - * @param {string} url The href of the link. - * @param {boolean} opensInNewWindow Whether this link will open in a new window. - * @param {Object} text The text that is being hyperlinked. + * @param {Object} options + * @param {string} options.url The href of the link. + * @param {boolean} options.opensInNewWindow Whether this link will open in a new window. + * @param {Object} options.text The text that is being hyperlinked. * * @return {Object} The final format object. */ diff --git a/packages/media-utils/src/components/media-upload/index.js b/packages/media-utils/src/components/media-upload/index.js index f97b6b1f432985..7dfd0d9812932d 100644 --- a/packages/media-utils/src/components/media-upload/index.js +++ b/packages/media-utils/src/components/media-upload/index.js @@ -18,7 +18,7 @@ const getGalleryDetailsMediaFrame = () => { * * @see https://github.com/xwp/wp-core-media-widgets/blob/905edbccfc2a623b73a93dac803c5335519d7837/wp-admin/js/widgets/media-gallery-widget.js * @class GalleryDetailsMediaFrame - * @constructor + * @class */ return wp.media.view.MediaFrame.Post.extend( { diff --git a/packages/notices/src/store/selectors.js b/packages/notices/src/store/selectors.js index 9ba3cec0e63a06..b5daf3e024ccde 100644 --- a/packages/notices/src/store/selectors.js +++ b/packages/notices/src/store/selectors.js @@ -15,7 +15,7 @@ import { DEFAULT_CONTEXT } from './constants'; const DEFAULT_NOTICES = []; /** - * Notice object. + * @typedef {Object} WPNotice Notice object. * * @property {string} id Unique identifier of notice. * @property {string} status Status of notice, one of `success`, @@ -31,11 +31,10 @@ const DEFAULT_NOTICES = []; * user. Defaults to `true`. * @property {WPNoticeAction[]} actions User actions to present with notice. * - * @typedef {WPNotice} */ /** - * Object describing a user action option associated with a notice. + * @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 @@ -43,7 +42,6 @@ const DEFAULT_NOTICES = []; * @property {?Function} callback Optional function to invoke when action is * triggered by user. * - * @typedef {WPNoticeAction} */ /** diff --git a/packages/redux-routine/src/runtime.js b/packages/redux-routine/src/runtime.js index ec984a148435e2..204f4c10eb7ffd 100644 --- a/packages/redux-routine/src/runtime.js +++ b/packages/redux-routine/src/runtime.js @@ -14,9 +14,9 @@ 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 {Function} dispatch Unhandled action dispatch. * - * @return {function} co-routine runtime + * @return {Function} co-routine runtime */ export default function createRuntime( controls = {}, dispatch ) { const rungenControls = map( controls, ( control, actionType ) => ( value, next, iterate, yieldNext, yieldError ) => { diff --git a/packages/rich-text/README.md b/packages/rich-text/README.md index a29d9d3f0dac3f..fe023b5faef75a 100644 --- a/packages/rich-text/README.md +++ b/packages/rich-text/README.md @@ -302,9 +302,13 @@ Indices are retrieved from the selection if none are provided. _Parameters_ -- _value_ `Object`: Value to modify. +- _richText_ `Object`: +- _richText.formats_ `Array`: +- _richText.replacements_ `Array`: +- _richText.text_ `string`: +- _richText.start_ `number`: +- _richText.end_ `number`: - _string_ `[(number|string)]`: Start index, or string at which to split. -- _endStr_ `[number]`: End index. _Returns_ diff --git a/packages/rich-text/src/component/index.js b/packages/rich-text/src/component/index.js index d16598417e2f78..0bccf89de37ab9 100644 --- a/packages/rich-text/src/component/index.js +++ b/packages/rich-text/src/component/index.js @@ -839,11 +839,11 @@ class RichText extends Component { } /** - * Converts the internal value to the external data format. - * - * @param {Object} value The internal rich-text value. - * @return {*} The external data format, data type depends on props. - */ + * Converts the internal value to the external data format. + * + * @param {Object} value The internal rich-text value. + * @return {*} The external data format, data type depends on props. + */ valueToFormat( value ) { value = this.removeEditorOnlyFormats( value ); diff --git a/packages/rich-text/src/component/index.native.js b/packages/rich-text/src/component/index.native.js index 441095f59d39fd..1cf45d08548bf0 100644 --- a/packages/rich-text/src/component/index.native.js +++ b/packages/rich-text/src/component/index.native.js @@ -47,7 +47,7 @@ const unescapeSpaces = ( text ) => { * Calls {@link pasteHandler} with a fallback to plain text when HTML processing * results in errors * - * @param {function} originalPasteHandler The original handler function + * @param {Function} originalPasteHandler The original handler function * @param {Object} [options] The options to pass to {@link pasteHandler} * * @return {Array|string} A list of blocks or a string, depending on diff --git a/packages/rich-text/src/split.js b/packages/rich-text/src/split.js index f79a675b1e1f4f..7432ff995da52d 100644 --- a/packages/rich-text/src/split.js +++ b/packages/rich-text/src/split.js @@ -9,9 +9,13 @@ import { replace } from './replace'; * split at the given separator. This is similar to `String.prototype.split`. * Indices are retrieved from the selection if none are provided. * - * @param {Object} value Value to modify. + * @param {Object} richText + * @param {Object[]} richText.formats + * @param {Object[]} richText.replacements + * @param {string} richText.text + * @param {number} richText.start + * @param {number} richText.end * @param {number|string} [string] Start index, or string at which to split. - * @param {number} [endStr] End index. * * @return {Array} An array of new values. */ diff --git a/packages/wordcount/README.md b/packages/wordcount/README.md index d987ddfeccd130..edc6ece7433695 100644 --- a/packages/wordcount/README.md +++ b/packages/wordcount/README.md @@ -29,13 +29,13 @@ const numberOfWords = count( 'Words to count', 'words', {} ) _Parameters_ -- _text_ `String`: The text being processed -- _type_ `String`: The type of count. Accepts ;words', 'characters_excluding_spaces', or 'characters_including_spaces'. +- _text_ `string`: The text being processed +- _type_ `string`: The type of count. Accepts ;words', 'characters_excluding_spaces', or 'characters_including_spaces'. - _userSettings_ `Object`: Custom settings object. _Returns_ -- `Number`: The word or character count. +- `number`: The word or character count. diff --git a/packages/wordcount/src/index.js b/packages/wordcount/src/index.js index 9099e523574cea..676f7ac2564b53 100644 --- a/packages/wordcount/src/index.js +++ b/packages/wordcount/src/index.js @@ -91,8 +91,8 @@ function matchCharacters( text, regex, settings ) { /** * Count some words. * - * @param {String} text The text being processed - * @param {String} type The type of count. Accepts ;words', 'characters_excluding_spaces', or 'characters_including_spaces'. + * @param {string} text The text being processed + * @param {string} type The type of count. Accepts ;words', 'characters_excluding_spaces', or 'characters_including_spaces'. * @param {Object} userSettings Custom settings object. * * @example @@ -101,7 +101,7 @@ function matchCharacters( text, regex, settings ) { * const numberOfWords = count( 'Words to count', 'words', {} ) * ``` * - * @return {Number} The word or character count. + * @return {number} The word or character count. */ export function count( text, type, userSettings ) { diff --git a/test/native/__mocks__/styleMock.js b/test/native/__mocks__/styleMock.js index 67e15440ddff34..182af41388dc0a 100644 --- a/test/native/__mocks__/styleMock.js +++ b/test/native/__mocks__/styleMock.js @@ -1,8 +1,4 @@ -/** @flow - * @format */ - module.exports = { - //Mock block paragraph style with minimum height blockText: { minHeight: 50, diff --git a/test/native/jest.config.js b/test/native/jest.config.js index 58a6f324cd6c62..e049d9416052c2 100644 --- a/test/native/jest.config.js +++ b/test/native/jest.config.js @@ -1,6 +1,3 @@ -/** @flow - * @format */ - /** * External dependencies */ From 49f99c180c0c9ffd7debab0c996b1676a13cb42d Mon Sep 17 00:00:00 2001 From: Derek Sifford Date: Fri, 2 Aug 2019 13:59:34 -0400 Subject: [PATCH 2/2] fix: address code review comments --- package-lock.json | 18 ------------------ packages/block-library/src/embed/util.js | 2 +- packages/rich-text/README.md | 12 ++++++------ packages/rich-text/src/split.js | 12 ++++++------ 4 files changed, 13 insertions(+), 31 deletions(-) diff --git a/package-lock.json b/package-lock.json index 80b9b46734c736..04093ff7f7b4fa 100644 --- a/package-lock.json +++ b/package-lock.json @@ -4078,25 +4078,7 @@ "eslint-plugin-jsx-a11y": "^6.2.1", "eslint-plugin-react": "^7.12.4", "eslint-plugin-react-hooks": "^1.6.0", - "globals": "^12.0.0", "requireindex": "^1.2.0" - }, - "dependencies": { - "globals": { - "version": "12.0.0", - "resolved": "https://registry.npmjs.org/globals/-/globals-12.0.0.tgz", - "integrity": "sha512-c9xoi32iDwlETiyYfO0pd3M8GcEuytJinSoqq7k3fz4H8p2p31NyfKr7JVd7Y0QvmtWcWXcwqW4L33eeDYgh1A==", - "dev": true, - "requires": { - "type-fest": "^0.6.0" - } - }, - "type-fest": { - "version": "0.6.0", - "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-0.6.0.tgz", - "integrity": "sha512-q+MB8nYR1KDLrgr4G5yemftpMC7/QLqVndBmEEdqzmNj5dcFOO4Oo8qlwZE3ULT3+Zim1F8Kq4cBnikNhlCMlg==", - "dev": true - } } }, "@wordpress/format-library": { diff --git a/packages/block-library/src/embed/util.js b/packages/block-library/src/embed/util.js index 04c66a4ff00ecc..0096f1bc3cd98a 100644 --- a/packages/block-library/src/embed/util.js +++ b/packages/block-library/src/embed/util.js @@ -68,7 +68,7 @@ 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} 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. */ diff --git a/packages/rich-text/README.md b/packages/rich-text/README.md index fe023b5faef75a..0b9187685ed7ee 100644 --- a/packages/rich-text/README.md +++ b/packages/rich-text/README.md @@ -302,12 +302,12 @@ Indices are retrieved from the selection if none are provided. _Parameters_ -- _richText_ `Object`: -- _richText.formats_ `Array`: -- _richText.replacements_ `Array`: -- _richText.text_ `string`: -- _richText.start_ `number`: -- _richText.end_ `number`: +- _value_ `Object`: +- _value.formats_ `Array`: +- _value.replacements_ `Array`: +- _value.text_ `string`: +- _value.start_ `number`: +- _value.end_ `number`: - _string_ `[(number|string)]`: Start index, or string at which to split. _Returns_ diff --git a/packages/rich-text/src/split.js b/packages/rich-text/src/split.js index 7432ff995da52d..05ef87fbe0c4f5 100644 --- a/packages/rich-text/src/split.js +++ b/packages/rich-text/src/split.js @@ -9,12 +9,12 @@ import { replace } from './replace'; * split at the given separator. This is similar to `String.prototype.split`. * Indices are retrieved from the selection if none are provided. * - * @param {Object} richText - * @param {Object[]} richText.formats - * @param {Object[]} richText.replacements - * @param {string} richText.text - * @param {number} richText.start - * @param {number} richText.end + * @param {Object} value + * @param {Object[]} value.formats + * @param {Object[]} value.replacements + * @param {string} value.text + * @param {number} value.start + * @param {number} value.end * @param {number|string} [string] Start index, or string at which to split. * * @return {Array} An array of new values.