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 05bd3906353ffc..5c6b79d9309963 100644 --- a/docs/designers-developers/developers/data/data-core-block-editor.md +++ b/docs/designers-developers/developers/data/data-core-block-editor.md @@ -115,7 +115,7 @@ _Parameters_ _Returns_ -- `?Object`: Block attributes. +- `Object?`: Block attributes. # **getBlockCount** @@ -259,7 +259,7 @@ _Parameters_ - _state_ `Object`: Editor state. - _clientId_ `string`: Block from which to find root client ID. -- _blockName_ `(string|Array)`: Block name(s) to filter. +- _blockName_ `string|string[]`: Block name(s) to filter. - _ascending_ `boolean`: Order results from bottom to top (true) or top to bottom (false). _Returns_ @@ -300,7 +300,7 @@ _Parameters_ _Returns_ -- `Array`: Post blocks. +- `Object[]`: Post blocks. # **getBlocksByClientId** @@ -310,11 +310,11 @@ objects. _Parameters_ - _state_ `Object`: Editor state. -- _clientIds_ `Array`: Client IDs for which blocks are to be returned. +- _clientIds_ `string[]`: Client IDs for which blocks are to be returned. _Returns_ -- `Array`: Block objects. +- `WPBlock[]`: Block objects. # **getBlockSelectionEnd** @@ -363,7 +363,7 @@ _Parameters_ _Returns_ -- `Array`: Items that appear in inserter. +- `WPEditorTransformItem[]`: Items that appear in inserter. _Type Definition_ @@ -417,7 +417,7 @@ _Parameters_ _Returns_ -- `Array`: Array of dragged block client ids. +- `string[]`: Array of dragged block client ids. # **getFirstMultiSelectedBlockClientId** @@ -466,7 +466,7 @@ _Parameters_ _Returns_ -- `Array`: Items that appear in inserter. +- `WPEditorInserterItem[]`: Items that appear in inserter. _Type Definition_ @@ -480,7 +480,7 @@ _Properties_ - _title_ `string`: Title of the item, as it appears in the inserter. - _icon_ `string`: Dashicon for the item, as it appears in the inserter. - _category_ `string`: Block category that the item is associated with. -- _keywords_ `Array`: Keywords that can be searched to find this item. +- _keywords_ `string[]`: Keywords that can be searched to find this item. - _isDisabled_ `boolean`: Whether or not the user should be prevented from inserting this item. - _frecency_ `number`: Heuristic that combines frequency and recency. @@ -665,7 +665,7 @@ _Parameters_ _Returns_ -- `(||null)`: Initial position. +- `0|-1|null`: Initial position. # **getSelectionEnd** @@ -1060,7 +1060,7 @@ Generator that triggers an action used to duplicate a list of blocks. _Parameters_ -- _clientIds_ `Array`: +- _clientIds_ `string[]`: - _updateSelection_ `boolean`: # **enterFormattedText** @@ -1135,11 +1135,11 @@ be inserted, optionally at a specific index respective a root block list. _Parameters_ -- _blocks_ `Array`: Block objects to insert. +- _blocks_ `Object[]`: Block objects to insert. - _index_ `?number`: Index at which block should be inserted. - _rootClientId_ `?string`: Optional root client ID of block list on which to insert. - _updateSelection_ `?boolean`: If true block selection will be updated. If false, block selection will not change. Defaults to true. -- _initialPosition_ `(||null)`: Initial focus position. Setting it to null prevent focusing the inserted block. +- _initialPosition_ `0|-1|null`: Initial focus position. Setting it to null prevent focusing the inserted block. - _meta_ `?Object`: Optional Meta values to be passed to the action object. _Returns_ @@ -1219,7 +1219,7 @@ replacing. _Parameters_ -- _blocks_ `Array`: Array of block objects. +- _blocks_ `Object[]`: Array of block objects. _Returns_ @@ -1246,7 +1246,7 @@ the set of specified client IDs are to be removed. _Parameters_ -- _clientIds_ `(string|Array)`: Client IDs of blocks to remove. +- _clientIds_ `string|string[]`: Client IDs of blocks to remove. - _selectPrevious_ `boolean`: True if the previous block should be selected when a block is removed. # **replaceBlock** @@ -1256,8 +1256,8 @@ with one or more replacement blocks. _Parameters_ -- _clientId_ `(string|Array)`: Block client ID to replace. -- _block_ `(Object|Array)`: Replacement block(s). +- _clientId_ `(string|string[])`: Block client ID to replace. +- _block_ `(Object|Object[])`: Replacement block(s). _Returns_ @@ -1270,10 +1270,10 @@ one or more replacement blocks. _Parameters_ -- _clientIds_ `(string|Array)`: Block client ID(s) to replace. -- _blocks_ `(Object|Array)`: Replacement block(s). +- _clientIds_ `(string|string[])`: Block client ID(s) to replace. +- _blocks_ `(Object|Object[])`: Replacement block(s). - _indexToSelect_ `number`: Index of replacement block to select. -- _initialPosition_ `(||null)`: Index of caret after in the selected block after the operation. +- _initialPosition_ `0|-1|null`: Index of caret after in the selected block after the operation. - _meta_ `?Object`: Optional Meta values to be passed to the action object. # **replaceInnerBlocks** @@ -1284,9 +1284,9 @@ specified client ID should be replaced. _Parameters_ - _rootClientId_ `string`: Client ID of the block whose InnerBlocks will re replaced. -- _blocks_ `Array`: Block objects to insert as new InnerBlocks +- _blocks_ `Object[]`: Block objects to insert as new InnerBlocks - _updateSelection_ `?boolean`: If true block selection will be updated. If false, block selection will not change. Defaults to false. -- _initialPosition_ `(||null)`: Initial block position. +- _initialPosition_ `0|-1|null`: Initial block position. _Returns_ @@ -1311,7 +1311,7 @@ _Parameters_ - _selectionStart_ `WPBlockSelection`: The selection start. - _selectionEnd_ `WPBlockSelection`: The selection end. -- _initialPosition_ `(||null)`: Initial block position. +- _initialPosition_ `0|-1|null`: Initial block position. _Returns_ @@ -1327,7 +1327,7 @@ reflects a reverse selection. _Parameters_ - _clientId_ `string`: Block client ID. -- _initialPosition_ `(||null)`: Optional initial position. Pass as -1 to reflect reverse selection. +- _initialPosition_ `0|-1|null`: Optional initial position. Pass as -1 to reflect reverse selection. _Returns_ @@ -1373,7 +1373,7 @@ Generator that triggers an action used to enable or disable the block moving mod _Parameters_ -- _hasBlockMovingClientId_ `(string|null)`: Enable/Disable block moving mode. +- _hasBlockMovingClientId_ `string|null`: Enable/Disable block moving mode. # **setHasControlledInnerBlocks** @@ -1425,7 +1425,7 @@ Returns an action object used in signalling that the user has begun to drag bloc _Parameters_ -- _clientIds_ `Array`: An array of client ids being dragged +- _clientIds_ `string[]`: An array of client ids being dragged _Returns_ @@ -1534,7 +1534,7 @@ attributes with the specified client IDs have been updated. _Parameters_ -- _clientIds_ `(string|Array)`: Block client IDs. +- _clientIds_ `string|string[]`: Block client IDs. - _attributes_ `Object`: Block attributes to be merged. _Returns_ diff --git a/docs/designers-developers/developers/data/data-core-blocks.md b/docs/designers-developers/developers/data/data-core-blocks.md index 655c4f0d7a3390..2e8c236bbf13a9 100644 --- a/docs/designers-developers/developers/data/data-core-blocks.md +++ b/docs/designers-developers/developers/data/data-core-blocks.md @@ -17,7 +17,7 @@ _Parameters_ _Returns_ -- `?Array`: Block Styles. +- `Array?`: Block Styles. # **getBlockSupport** @@ -45,7 +45,7 @@ _Parameters_ _Returns_ -- `?Object`: Block Type. +- `Object?`: Block Type. # **getBlockTypes** @@ -71,7 +71,7 @@ _Parameters_ _Returns_ -- `(Array|void)`: Block variations. +- `(WPBlockVariation[]|void)`: Block variations. # **getCategories** @@ -83,7 +83,7 @@ _Parameters_ _Returns_ -- `Array`: Categories list. +- `WPBlockCategory[]`: Categories list. # **getChildBlockNames** @@ -120,7 +120,7 @@ _Parameters_ _Returns_ -- `?string`: Default block name. +- `string?`: Default block name. # **getDefaultBlockVariation** @@ -149,7 +149,7 @@ _Parameters_ _Returns_ -- `?string`: Name of the block for handling non-block content. +- `string?`: Name of the block for handling non-block content. # **getGroupingBlockName** @@ -161,7 +161,7 @@ _Parameters_ _Returns_ -- `?string`: Name of the block for handling unregistered blocks. +- `string?`: Name of the block for handling unregistered blocks. # **getUnregisteredFallbackBlockName** @@ -173,7 +173,7 @@ _Parameters_ _Returns_ -- `?string`: Name of the block for handling unregistered blocks. +- `string?`: Name of the block for handling unregistered blocks. # **hasBlockSupport** @@ -229,7 +229,7 @@ _Parameters_ _Returns_ -- `Array`: Whether block type matches search term. +- `Object[]`: Whether block type matches search term. @@ -258,7 +258,7 @@ Returns an action object used in signalling that new block styles have been adde _Parameters_ - _blockName_ `string`: Block name. -- _styles_ `(Array|Object)`: Block styles. +- _styles_ `Array|Object`: Block styles. _Returns_ @@ -270,7 +270,7 @@ Returns an action object used in signalling that block types have been added. _Parameters_ -- _blockTypes_ `(Array|Object)`: Block types received. +- _blockTypes_ `Array|Object`: Block types received. _Returns_ @@ -283,7 +283,7 @@ Returns an action object used in signalling that new block variations have been _Parameters_ - _blockName_ `string`: Block name. -- _variations_ `(WPBlockVariation|Array)`: Block variations. +- _variations_ `WPBlockVariation|WPBlockVariation[]`: Block variations. _Returns_ @@ -308,7 +308,7 @@ Returns an action object used in signalling that block styles have been removed. _Parameters_ - _blockName_ `string`: Block name. -- _styleNames_ `(Array|string)`: Block style names. +- _styleNames_ `Array|string`: Block style names. _Returns_ @@ -320,7 +320,7 @@ Returns an action object used to remove a registered block type. _Parameters_ -- _names_ `(string|Array)`: Block name. +- _names_ `string|Array`: Block name. _Returns_ @@ -333,7 +333,7 @@ Returns an action object used in signalling that block variations have been remo _Parameters_ - _blockName_ `string`: Block name. -- _variationNames_ `(string|Array)`: Block variation names. +- _variationNames_ `string|string[]`: Block variation names. _Returns_ @@ -345,7 +345,7 @@ Returns an action object used to set block categories. _Parameters_ -- _categories_ `Array`: Block categories. +- _categories_ `Object[]`: Block categories. _Returns_ diff --git a/docs/designers-developers/developers/data/data-core-edit-post.md b/docs/designers-developers/developers/data/data-core-edit-post.md index ddaac2ac0ca707..63e1f1ba6b69f0 100644 --- a/docs/designers-developers/developers/data/data-core-edit-post.md +++ b/docs/designers-developers/developers/data/data-core-edit-post.md @@ -35,7 +35,7 @@ _Parameters_ _Returns_ -- `Array`: Active meta box locations. +- `string[]`: Active meta box locations. # **getAllMetaBoxes** @@ -325,7 +325,7 @@ name(s) should be hidden. _Parameters_ -- _blockNames_ `Array`: Names of block types to hide. +- _blockNames_ `string[]`: Names of block types to hide. _Returns_ @@ -424,7 +424,7 @@ name(s) should be shown. _Parameters_ -- _blockNames_ `Array`: Names of block types to show. +- _blockNames_ `string[]`: Names of block types to show. _Returns_ diff --git a/docs/designers-developers/developers/data/data-core-editor.md b/docs/designers-developers/developers/data/data-core-editor.md index 86e57d27a53e36..4fbce4a3c1b932 100644 --- a/docs/designers-developers/developers/data/data-core-editor.md +++ b/docs/designers-developers/developers/data/data-core-editor.md @@ -203,7 +203,7 @@ _Parameters_ _Returns_ -- `Array`: Filtered set of blocks for save. +- `WPBlock[]`: Filtered set of blocks for save. # **getClientIdsOfDescendants** @@ -331,7 +331,7 @@ _Parameters_ _Returns_ -- `?string`: Preview Link. +- `string?`: Preview Link. # **getEditedPostSlug** @@ -796,7 +796,7 @@ Return true if the current post has already been published. _Parameters_ - _state_ `Object`: Global application state. -- _currentPost_ `?Object`: Explicit current post for bypassing registry selector. +- _currentPost_ `Object?`: Explicit current post for bypassing registry selector. _Returns_ @@ -1077,7 +1077,7 @@ Storage). _Parameters_ -- _options_ `?Object`: Extra flags to identify the autosave. +- _options_ `Object?`: Extra flags to identify the autosave. # **clearSelectedBlock** @@ -1363,7 +1363,7 @@ _Parameters_ - _post_ `Object`: Post object. - _edits_ `Object`: Initial edited attributes object. -- _template_ `?Array`: Block Template. +- _template_ `Array?`: Block Template. # **setupEditorState** diff --git a/docs/designers-developers/developers/data/data-core-keyboard-shortcuts.md b/docs/designers-developers/developers/data/data-core-keyboard-shortcuts.md index fefa8e189e2150..9211b1c4808370 100644 --- a/docs/designers-developers/developers/data/data-core-keyboard-shortcuts.md +++ b/docs/designers-developers/developers/data/data-core-keyboard-shortcuts.md @@ -17,7 +17,7 @@ _Parameters_ _Returns_ -- `Array`: Shortcuts. +- `string[]`: Shortcuts. # **getCategoryShortcuts** @@ -30,7 +30,7 @@ _Parameters_ _Returns_ -- `Array`: Shortcut names. +- `string[]`: Shortcut names. # **getShortcutAliases** @@ -43,7 +43,7 @@ _Parameters_ _Returns_ -- `Array`: Key combinations. +- `WPShortcutKeyCombination[]`: Key combinations. # **getShortcutDescription** @@ -56,7 +56,7 @@ _Parameters_ _Returns_ -- `?string`: Shortcut description. +- `string?`: Shortcut description. # **getShortcutKeyCombination** @@ -69,7 +69,7 @@ _Parameters_ _Returns_ -- `?WPShortcutKeyCombination`: Key combination. +- `WPShortcutKeyCombination?`: Key combination. # **getShortcutRepresentation** @@ -79,11 +79,11 @@ _Parameters_ - _state_ `Object`: Global state. - _name_ `string`: Shortcut name. -- _representation_ (unknown type): Type of representation (display, raw, ariaLabel). +- _representation_ `keyof FORMATTING_METHODS`: Type of representation (display, raw, ariaLabel). _Returns_ -- `?string`: Shortcut representation. +- `string?`: Shortcut representation. diff --git a/docs/designers-developers/developers/data/data-core-notices.md b/docs/designers-developers/developers/data/data-core-notices.md index 0ecaa5cc3a7a19..87066f5e0f4c37 100644 --- a/docs/designers-developers/developers/data/data-core-notices.md +++ b/docs/designers-developers/developers/data/data-core-notices.md @@ -18,7 +18,7 @@ _Parameters_ _Returns_ -- `Array`: Array of notices. +- `WPNotice[]`: Array of notices. diff --git a/docs/designers-developers/developers/data/data-core-nux.md b/docs/designers-developers/developers/data/data-core-nux.md index ad0a93e2bde235..2abad5d1f52775 100644 --- a/docs/designers-developers/developers/data/data-core-nux.md +++ b/docs/designers-developers/developers/data/data-core-nux.md @@ -90,7 +90,7 @@ the user through a series of tips step by step. _Parameters_ -- _tipIds_ `Array`: Which tips to show in the guide. +- _tipIds_ `string[]`: Which tips to show in the guide. _Returns_ diff --git a/docs/designers-developers/developers/data/data-core.md b/docs/designers-developers/developers/data/data-core.md index a901c5080b83f0..4f9f16e4eab8a9 100644 --- a/docs/designers-developers/developers/data/data-core.md +++ b/docs/designers-developers/developers/data/data-core.md @@ -21,11 +21,11 @@ _Parameters_ - _state_ `Object`: Data state. - _action_ `string`: Action to check. One of: 'create', 'read', 'update', 'delete'. - _resource_ `string`: REST resource to check, e.g. 'media' or 'posts'. -- _id_ `[string]`: Optional ID of the rest resource to check. +- _id_ `string=`: Optional ID of the rest resource to check. _Returns_ -- `(boolean|undefined)`: Whether or not the user can perform the action, or `undefined` if the OPTIONS request is still being made. +- `boolean|undefined`: Whether or not the user can perform the action, or `undefined` if the OPTIONS request is still being made. # **getAuthors** @@ -34,7 +34,7 @@ Returns all available authors. _Parameters_ - _state_ `Object`: Data state. -- _query_ `(Object|undefined)`: Optional object of query parameters to include with request. +- _query_ `Object|undefined`: Optional object of query parameters to include with request. _Returns_ @@ -109,7 +109,7 @@ _Parameters_ _Returns_ -- `?Object`: The entity record, merged with its edits. +- `Object?`: The entity record, merged with its edits. # **getEmbedPreview** @@ -167,7 +167,7 @@ _Parameters_ _Returns_ -- `?Object`: Record. +- `Object?`: Record. # **getEntityRecordEdits** @@ -182,7 +182,7 @@ _Parameters_ _Returns_ -- `?Object`: The entity record's edits. +- `Object?`: The entity record's edits. # **getEntityRecordNonTransientEdits** @@ -201,7 +201,7 @@ _Parameters_ _Returns_ -- `?Object`: The entity record's non transient edits. +- `Object?`: The entity record's non transient edits. # **getEntityRecords** @@ -231,7 +231,7 @@ _Parameters_ _Returns_ -- `?Object`: The entity record's save error. +- `Object?`: The entity record's save error. # **getLastEntitySaveError** @@ -246,7 +246,7 @@ _Parameters_ _Returns_ -- `?Object`: The entity record's save error. +- `Object?`: The entity record's save error. # **getRawEntityRecord** @@ -262,7 +262,7 @@ _Parameters_ _Returns_ -- `?Object`: Object with the entity's raw attributes. +- `Object?`: Object with the entity's raw attributes. # **getRedoEdit** @@ -275,7 +275,7 @@ _Parameters_ _Returns_ -- `?Object`: The edit. +- `Object?`: The edit. # **getReferenceByDistinctEdits** @@ -321,7 +321,7 @@ _Parameters_ _Returns_ -- `?Object`: The edit. +- `Object?`: The edit. # **getUserQueryResults** @@ -560,7 +560,7 @@ post have been received. _Parameters_ - _postId_ `number`: The id of the post that is parent to the autosave. -- _autosaves_ `(Array|Object)`: An array of autosaves or singular autosave object. +- _autosaves_ `Array|Object`: An array of autosaves or singular autosave object. _Returns_ @@ -612,7 +612,7 @@ _Parameters_ - _kind_ `string`: Kind of the received entity. - _name_ `string`: Name of the received entity. -- _records_ `(Array|Object)`: Records received. +- _records_ `Array|Object`: Records received. - _query_ `?Object`: Query Object. - _invalidateCache_ `?boolean`: Should invalidate query caches. - _edits_ `?Object`: Edits to reset. @@ -666,7 +666,7 @@ Returns an action object used in signalling that authors have been received. _Parameters_ - _queryID_ `string`: Query ID. -- _users_ `(Array|Object)`: Users received. +- _users_ `Array|Object`: Users received. _Returns_ diff --git a/package-lock.json b/package-lock.json index 3fd526aa487065..41f88297f1aae8 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12107,13 +12107,21 @@ "dev": true, "requires": { "@babel/core": "^7.12.9", - "doctrine": "^2.1.0", + "comment-parser": "^1.1.1", "lodash": "^4.17.19", "mdast-util-inject": "1.1.0", "optionator": "0.8.2", "remark": "10.0.1", "remark-parse": "6.0.3", "unified": "7.1.0" + }, + "dependencies": { + "comment-parser": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/comment-parser/-/comment-parser-1.1.1.tgz", + "integrity": "sha512-vue7cRi1ZO5/72FJ+wZ5+siTSBlUv3ZksTk8bWD2IkaA6obitzMZP3yI65azTJLckwmi8lxfPP5Sd9oGuZ8e2g==", + "dev": true + } } }, "@wordpress/dom": { diff --git a/packages/blob/README.md b/packages/blob/README.md index 91a371d1d71260..f49f493d175651 100644 --- a/packages/blob/README.md +++ b/packages/blob/README.md @@ -38,7 +38,7 @@ _Parameters_ _Returns_ -- `(File|undefined)`: The file for the blob URL. +- `File|undefined`: The file for the blob URL. # **getBlobTypeByURL** @@ -52,7 +52,7 @@ _Parameters_ _Returns_ -- `(string|undefined)`: The blob type. +- `string|undefined`: The blob type. # **isBlobURL** diff --git a/packages/block-directory/README.md b/packages/block-directory/README.md index 77b6f9afc551b0..f43474acffb7af 100644 --- a/packages/block-directory/README.md +++ b/packages/block-directory/README.md @@ -172,7 +172,7 @@ _Parameters_ _Returns_ -- `(string|boolean)`: The error text, or false if no error. +- `string|boolean`: The error text, or false if no error. # **getErrorNotices** diff --git a/packages/block-editor/README.md b/packages/block-editor/README.md index 0515228f27a592..31c2dde299bb94 100644 --- a/packages/block-editor/README.md +++ b/packages/block-editor/README.md @@ -165,7 +165,7 @@ _Related_ _Parameters_ - _preview_ `Object`: options for how the preview should be shown -- _preview.blocks_ `(Array|Object)`: A block instance (object) or an array of blocks to be previewed. +- _preview.blocks_ `Array|Object`: A block instance (object) or an array of blocks to be previewed. - _preview.viewportWidth_ `number`: Width of the preview container in pixels. Controls at what size the blocks will be rendered inside the preview. Default: 700. _Returns_ @@ -316,7 +316,7 @@ _Returns_ # **getFontSize** -Returns the font size object based on an array of named font sizes and the namedFontSize and customFontSize values. + Returns the font size object based on an array of named font sizes and the namedFontSize and customFontSize values. If namedFontSize is undefined or not found in fontSizes an object with just the size value based on customFontSize is returned. _Parameters_ @@ -490,7 +490,7 @@ _Properties_ - _imageEditing_ `boolean`: Image Editing settings set to false to disable. - _imageSizes_ `Array`: Available image sizes - _maxWidth_ `number`: Max width to constraint resizing -- _allowedBlockTypes_ `(boolean|Array)`: Allowed block types +- _allowedBlockTypes_ `boolean|Array`: Allowed block types - _hasFixedToolbar_ `boolean`: Whether or not the editor toolbar is fixed - _focusMode_ `boolean`: Whether the focus mode is enabled or not - _styles_ `Array`: Editor Styles diff --git a/packages/blocks/README.md b/packages/blocks/README.md index f2347725ba74b9..5b9266a7f77db6 100644 --- a/packages/blocks/README.md +++ b/packages/blocks/README.md @@ -223,7 +223,7 @@ _Parameters_ _Returns_ -- `Array`: Array of Block objects. +- `Object[]`: Array of Block objects. # **doBlocksMatchTemplate** @@ -248,7 +248,7 @@ falsey value for all entries. _Parameters_ -- _transforms_ `Array`: Transforms to search. +- _transforms_ `Object[]`: Transforms to search. - _predicate_ `Function`: Function returning true on matching transform. _Returns_ @@ -261,7 +261,7 @@ Returns the block attributes of a registered block node given its type. _Parameters_ -- _blockTypeOrName_ `(string|Object)`: Block type or name. +- _blockTypeOrName_ `string|Object`: Block type or name. - _innerHTML_ `string`: Raw block content. - _attributes_ `?Object`: Known block attributes (from delimiters). @@ -342,7 +342,7 @@ transform object includes `blockName` as a property. _Parameters_ - _direction_ `string`: Transform direction ("to", "from"). -- _blockTypeOrName_ `(string|Object)`: Block type or name. +- _blockTypeOrName_ `string|Object`: Block type or name. _Returns_ @@ -379,7 +379,7 @@ _Parameters_ _Returns_ -- `(Array|void)`: Block variations. +- `(WPBlockVariation[]|void)`: Block variations. # **getCategories** @@ -387,7 +387,7 @@ Returns all the block categories. _Returns_ -- `Array`: Block categories. +- `WPBlockCategory[]`: Block categories. # **getChildBlockNames** @@ -450,7 +450,7 @@ static markup to be saved. _Parameters_ -- _blockTypeOrName_ `(string|Object)`: Block type or name. +- _blockTypeOrName_ `string|Object`: Block type or name. - _attributes_ `Object`: Block attributes. - _innerBlocks_ `?Array`: Nested blocks. @@ -465,13 +465,13 @@ enhanced element to be saved or string when raw HTML expected. _Parameters_ -- _blockTypeOrName_ `(string|Object)`: Block type or name. +- _blockTypeOrName_ `string|Object`: Block type or name. - _attributes_ `Object`: Block attributes. - _innerBlocks_ `?Array`: Nested blocks. _Returns_ -- `(Object|string)`: Save element or raw HTML string. +- `Object|string`: Save element or raw HTML string. # **getUnregisteredTypeHandlerName** @@ -572,7 +572,7 @@ Logs to console in development environments when invalid. _Parameters_ -- _blockTypeOrName_ `(string|Object)`: Block type. +- _blockTypeOrName_ `string|Object`: Block type. - _attributes_ `Object`: Parsed block attributes. - _originalBlockContent_ `string`: Original block content. @@ -661,7 +661,7 @@ _Parameters_ _Returns_ -- `(Array|string)`: A list of blocks or a string, depending on `handlerMode`. +- `Array|string`: A list of blocks or a string, depending on `handlerMode`. # **rawHandler** @@ -739,7 +739,7 @@ Sets the block categories. _Parameters_ -- _categories_ `Array`: Block categories. +- _categories_ `WPBlockCategory[]`: Block categories. # **setDefaultBlockName** @@ -791,7 +791,7 @@ Switch one or more blocks into one or more blocks of the new block type. _Parameters_ -- _blocks_ `(Array|Object)`: Blocks array or block object. +- _blocks_ `Array|Object`: Blocks array or block object. - _name_ `string`: Block name. _Returns_ diff --git a/packages/compose/README.md b/packages/compose/README.md index 0e831c454e2166..15f56a39595fbb 100644 --- a/packages/compose/README.md +++ b/packages/compose/README.md @@ -155,7 +155,7 @@ const ConstrainedTabbingExample = () => { _Returns_ -- `(Object|Function)`: Element Ref. +- `Object|Function`: Element Ref. # **useCopyOnClick** @@ -164,7 +164,7 @@ Copies the text to the clipboard when the element is clicked. _Parameters_ - _ref_ `Object`: Reference with the element. -- _text_ `(string|Function)`: The text to copy. +- _text_ `string|Function`: The text to copy. - _timeout_ `number`: Optional timeout to reset the returned state. 4 seconds by default. _Returns_ @@ -208,7 +208,7 @@ const WithFocusOnMount = () => { _Parameters_ -- _focusOnMount_ `(boolean|string)`: Focus on mount mode. +- _focusOnMount_ `boolean|string`: Focus on mount mode. _Returns_ @@ -239,7 +239,7 @@ const WithFocusReturn = () => { _Parameters_ -- _onFocusReturn_ `?Function`: Overrides the default return behavior. +- _onFocusReturn_ `Function?`: Overrides the default return behavior. _Returns_ @@ -257,7 +257,7 @@ _Parameters_ _Returns_ -- `(string|number)`: The unique instance id. +- `string | number`: The unique instance id. # **useIsomorphicLayoutEffect** @@ -271,7 +271,7 @@ Attach a keyboard shortcut handler. _Parameters_ -- _shortcuts_ `(Array|string)`: Keyboard Shortcuts. +- _shortcuts_ `string[]|string`: Keyboard Shortcuts. - _callback_ `Function`: Shortcut callback. - _options_ `WPKeyboardShortcutConfig`: Shortcut options. @@ -299,7 +299,7 @@ with the same node. _Parameters_ -- _refs_ `Array<(RefObject|RefCallback)>`: The refs to be merged. +- _refs_ `Array`: The refs to be merged. _Returns_ @@ -316,7 +316,7 @@ _Parameters_ _Returns_ -- `(T|undefined)`: The value from the previous render. +- `T|undefined`: The value from the previous render. # **useReducedMotion** diff --git a/packages/core-data/README.md b/packages/core-data/README.md index 793be653074575..21cb97b56a65a3 100644 --- a/packages/core-data/README.md +++ b/packages/core-data/README.md @@ -93,7 +93,7 @@ post have been received. _Parameters_ - _postId_ `number`: The id of the post that is parent to the autosave. -- _autosaves_ `(Array|Object)`: An array of autosaves or singular autosave object. +- _autosaves_ `Array|Object`: An array of autosaves or singular autosave object. _Returns_ @@ -145,7 +145,7 @@ _Parameters_ - _kind_ `string`: Kind of the received entity. - _name_ `string`: Name of the received entity. -- _records_ `(Array|Object)`: Records received. +- _records_ `Array|Object`: Records received. - _query_ `?Object`: Query Object. - _invalidateCache_ `?boolean`: Should invalidate query caches. - _edits_ `?Object`: Edits to reset. @@ -199,7 +199,7 @@ Returns an action object used in signalling that authors have been received. _Parameters_ - _queryID_ `string`: Query ID. -- _users_ `(Array|Object)`: Users received. +- _users_ `Array|Object`: Users received. _Returns_ @@ -262,11 +262,11 @@ _Parameters_ - _state_ `Object`: Data state. - _action_ `string`: Action to check. One of: 'create', 'read', 'update', 'delete'. - _resource_ `string`: REST resource to check, e.g. 'media' or 'posts'. -- _id_ `[string]`: Optional ID of the rest resource to check. +- _id_ `string=`: Optional ID of the rest resource to check. _Returns_ -- `(boolean|undefined)`: Whether or not the user can perform the action, or `undefined` if the OPTIONS request is still being made. +- `boolean|undefined`: Whether or not the user can perform the action, or `undefined` if the OPTIONS request is still being made. # **getAuthors** @@ -275,7 +275,7 @@ Returns all available authors. _Parameters_ - _state_ `Object`: Data state. -- _query_ `(Object|undefined)`: Optional object of query parameters to include with request. +- _query_ `Object|undefined`: Optional object of query parameters to include with request. _Returns_ @@ -350,7 +350,7 @@ _Parameters_ _Returns_ -- `?Object`: The entity record, merged with its edits. +- `Object?`: The entity record, merged with its edits. # **getEmbedPreview** @@ -408,7 +408,7 @@ _Parameters_ _Returns_ -- `?Object`: Record. +- `Object?`: Record. # **getEntityRecordEdits** @@ -423,7 +423,7 @@ _Parameters_ _Returns_ -- `?Object`: The entity record's edits. +- `Object?`: The entity record's edits. # **getEntityRecordNonTransientEdits** @@ -442,7 +442,7 @@ _Parameters_ _Returns_ -- `?Object`: The entity record's non transient edits. +- `Object?`: The entity record's non transient edits. # **getEntityRecords** @@ -472,7 +472,7 @@ _Parameters_ _Returns_ -- `?Object`: The entity record's save error. +- `Object?`: The entity record's save error. # **getLastEntitySaveError** @@ -487,7 +487,7 @@ _Parameters_ _Returns_ -- `?Object`: The entity record's save error. +- `Object?`: The entity record's save error. # **getRawEntityRecord** @@ -503,7 +503,7 @@ _Parameters_ _Returns_ -- `?Object`: Object with the entity's raw attributes. +- `Object?`: Object with the entity's raw attributes. # **getRedoEdit** @@ -516,7 +516,7 @@ _Parameters_ _Returns_ -- `?Object`: The edit. +- `Object?`: The edit. # **getReferenceByDistinctEdits** @@ -562,7 +562,7 @@ _Parameters_ _Returns_ -- `?Object`: The edit. +- `Object?`: The edit. # **getUserQueryResults** diff --git a/packages/data-controls/README.md b/packages/data-controls/README.md index dfc8e37b7760cd..3168fb4c1d6029 100644 --- a/packages/data-controls/README.md +++ b/packages/data-controls/README.md @@ -74,7 +74,7 @@ resolvers, _Parameters_ -- _paths_ (unknown type): +- _paths_ ``: _Returns_ diff --git a/packages/data/README.md b/packages/data/README.md index 1b09af3d10643d..a921597b59a03d 100644 --- a/packages/data/README.md +++ b/packages/data/README.md @@ -385,7 +385,7 @@ configurations. _Parameters_ - _storeConfigs_ `Object`: Initial store configurations. -- _parent_ `?Object`: Parent registry. +- _parent_ `Object?`: Parent registry. _Returns_ @@ -484,7 +484,7 @@ dispatch( 'my-shop' ).setPrice( 'hammer', 9.75 ); _Parameters_ -- _storeNameOrDefinition_ `(string|WPDataStore)`: Unique namespace identifier for the store or the store definition. +- _storeNameOrDefinition_ `string|WPDataStore`: Unique namespace identifier for the store or the store definition. _Returns_ @@ -608,7 +608,7 @@ resolveSelect( 'my-shop' ).getPrice( 'hammer' ).then(console.log) _Parameters_ -- _storeNameOrDefinition_ `(string|WPDataStore)`: Unique namespace identifier for the store or the store definition. +- _storeNameOrDefinition_ `string|WPDataStore`: Unique namespace identifier for the store or the store definition. _Returns_ @@ -630,7 +630,7 @@ select( 'my-shop' ).getPrice( 'hammer' ); _Parameters_ -- _storeNameOrDefinition_ `(string|WPDataStore)`: Unique namespace identifier for the store or the store definition. +- _storeNameOrDefinition_ `string|WPDataStore`: Unique namespace identifier for the store or the store definition. _Returns_ @@ -711,7 +711,7 @@ const SaleButton = ( { children } ) => { _Parameters_ -- _storeNameOrDefinition_ `[(string|WPDataStore)]`: Optionally provide the name of the store or its definition from which to retrieve action creators. If not provided, the registry.dispatch function is returned instead. +- _storeNameOrDefinition_ `[string|WPDataStore]`: Optionally provide the name of the store or its definition from which to retrieve action creators. If not provided, the registry.dispatch function is returned instead. _Returns_ diff --git a/packages/date/README.md b/packages/date/README.md index 954ea388ece67d..8ac658a2197a8c 100644 --- a/packages/date/README.md +++ b/packages/date/README.md @@ -28,8 +28,8 @@ _Related_ _Parameters_ - _dateFormat_ `string`: PHP-style formatting string. See php.net/date. -- _dateValue_ `(Date|string|Moment|null)`: Date object or string, parsable by moment.js. -- _timezone_ `(string|number|null)`: Timezone to output result in or a UTC offset. Defaults to timezone from site. +- _dateValue_ `Date|string|Moment|null`: Date object or string, parsable by moment.js. +- _timezone_ `string|number|null`: Timezone to output result in or a UTC offset. Defaults to timezone from site. _Returns_ @@ -50,8 +50,8 @@ _Related_ _Parameters_ - _dateFormat_ `string`: PHP-style formatting string. See php.net/date. -- _dateValue_ `(Date|string|Moment|null)`: Date object or string, parsable by moment.js. -- _timezone_ `(string|number|boolean|null)`: Timezone to output result in or a UTC offset. Defaults to timezone from site. Notice: `boolean` is effectively deprecated, but still supported for backward compatibility reasons. +- _dateValue_ `Date|string|Moment|null`: Date object or string, parsable by moment.js. +- _timezone_ `string|number|boolean|null`: Timezone to output result in or a UTC offset. Defaults to timezone from site. Notice: `boolean` is effectively deprecated, but still supported for backward compatibility reasons. _Returns_ @@ -64,7 +64,7 @@ Formats a date. Does not alter the date's timezone. _Parameters_ - _dateFormat_ `string`: PHP-style formatting string. See php.net/date. -- _dateValue_ `(Date|string|Moment|null)`: Date object or string, parsable by moment.js. +- _dateValue_ `Date|string|Moment|null`: Date object or string, parsable by moment.js. _Returns_ @@ -76,7 +76,7 @@ Create and return a JavaScript Date Object from a date string in the WP timezone _Parameters_ -- _dateString_ `?string`: Date formatted in the WP timezone. +- _dateString_ `string?`: Date formatted in the WP timezone. _Returns_ @@ -89,7 +89,7 @@ Formats a date (like `date()` in PHP), in the UTC timezone. _Parameters_ - _dateFormat_ `string`: PHP-style formatting string. See php.net/date. -- _dateValue_ `(Date|string|Moment|null)`: Date object or string, parsable by moment.js. +- _dateValue_ `Date|string|Moment|null`: Date object or string, parsable by moment.js. _Returns_ @@ -103,7 +103,7 @@ and using the UTC timezone. _Parameters_ - _dateFormat_ `string`: PHP-style formatting string. See php.net/date. -- _dateValue_ `(Date|string|Moment|null)`: Date object or string, parsable by moment.js. +- _dateValue_ `Date|string|Moment|null`: Date object or string, parsable by moment.js. _Returns_ diff --git a/packages/deprecated/README.md b/packages/deprecated/README.md index 756d6662159e23..491752b291f104 100644 --- a/packages/deprecated/README.md +++ b/packages/deprecated/README.md @@ -68,7 +68,7 @@ message is only logged once. _Type_ -- `Record` +- `Record` diff --git a/packages/docgen/CHANGELOG.md b/packages/docgen/CHANGELOG.md index 9901e6dd87bbb1..2c433a1c125bff 100644 --- a/packages/docgen/CHANGELOG.md +++ b/packages/docgen/CHANGELOG.md @@ -2,6 +2,8 @@ ## Unreleased +- Replace deprecated `doctrine` parser with simpler `comment-parser` to support a wider variety of types. This also de-normalizes types such that types will be transcribed exactly as they are declared in the doc comments. + ## 1.7.0 (2020-02-04) ### Bug Fixes diff --git a/packages/docgen/lib/get-jsdoc-from-token.js b/packages/docgen/lib/get-jsdoc-from-token.js index ce95d2c439f945..7c5a09ff99fef8 100644 --- a/packages/docgen/lib/get-jsdoc-from-token.js +++ b/packages/docgen/lib/get-jsdoc-from-token.js @@ -1,13 +1,12 @@ /** * External dependencies */ -const doctrine = require( 'doctrine' ); +const commentParser = require( 'comment-parser' ); /** * Internal dependencies */ const getLeadingComments = require( './get-leading-comments' ); -const getTypeAsString = require( './get-type-as-string' ); /** * Function that takes an Espree token and returns @@ -21,17 +20,20 @@ module.exports = ( token ) => { let jsdoc; const comments = getLeadingComments( token ); if ( comments && /^\*\r?\n/.test( comments ) ) { - jsdoc = doctrine.parse( comments, { - unwrap: true, - recoverable: true, - sloppy: true, - } ); - jsdoc.tags = jsdoc.tags.map( ( tag ) => { - if ( tag.type ) { - tag.type = getTypeAsString( tag.type ); - } - return tag; - } ); + jsdoc = commentParser.parse( `/*${ comments }*/`, { + spacing: 'preserve', + } )[ 0 ]; + if ( jsdoc ) { + jsdoc.tags = jsdoc.tags.map( ( tag ) => { + return { + ...tag, + description: + tag.description === '\n' + ? tag.description.trim() + : tag.description, + }; + } ); + } } return jsdoc; }; diff --git a/packages/docgen/lib/get-symbol-tags-by-name.js b/packages/docgen/lib/get-symbol-tags-by-name.js index 194077cf11c9e4..050bf3059951b4 100644 --- a/packages/docgen/lib/get-symbol-tags-by-name.js +++ b/packages/docgen/lib/get-symbol-tags-by-name.js @@ -9,7 +9,7 @@ */ function getSymbolTagsByName( symbol, ...names ) { return symbol.tags.filter( ( tag ) => { - return names.some( ( name ) => name === tag.title ); + return names.some( ( name ) => name === tag.tag ); } ); } diff --git a/packages/docgen/lib/markdown/formatter.js b/packages/docgen/lib/markdown/formatter.js index 7f1158e5b37165..49d09937d985ad 100644 --- a/packages/docgen/lib/markdown/formatter.js +++ b/packages/docgen/lib/markdown/formatter.js @@ -41,7 +41,9 @@ const formatDeprecated = ( tags, docs ) => { docs.push( ...tags.map( ( tag ) => - `\n> **Deprecated** ${ cleanSpaces( tag.description ) }` + `\n> **Deprecated** ${ cleanSpaces( + `${ tag.name } ${ tag.description }` + ) }` ) ); } @@ -61,8 +63,11 @@ const getSymbolHeading = ( text ) => { return `# **${ text }**`; }; -const getTypeOutput = ( type ) => { - return type ? `\`${ type }\`` : '(unknown type)'; +const getTypeOutput = ( tag ) => { + if ( tag.optional ) { + return `\`[${ tag.type }]\``; + } + return `\`${ tag.type }\``; }; module.exports = ( @@ -102,7 +107,10 @@ module.exports = ( formatTag( 'Related', getSymbolTagsByName( symbol, 'see', 'link' ), - ( tag ) => `\n- ${ tag.description }`, + ( tag ) => + `\n- ${ tag.name.trim() }${ + tag.description ? ' ' : '' + }${ tag.description.trim() }`, docs ); formatExamples( getSymbolTagsByName( symbol, 'example' ), docs ); @@ -110,8 +118,8 @@ module.exports = ( 'Type', getSymbolTagsByName( symbol, 'type' ), ( tag ) => - `\n- ${ getTypeOutput( tag.type ) } ${ cleanSpaces( - tag.description + `\n- ${ getTypeOutput( tag ) } ${ cleanSpaces( + `${ tag.name } ${ tag.description }` ) }`, docs ); @@ -120,23 +128,24 @@ module.exports = ( getSymbolTagsByName( symbol, 'param' ), ( tag ) => `\n- *${ tag.name }* ${ getTypeOutput( - tag.type + tag ) }: ${ cleanSpaces( tag.description ) }`, docs ); formatTag( 'Returns', getSymbolTagsByName( symbol, 'return' ), - ( tag ) => - `\n- ${ getTypeOutput( tag.type ) }: ${ cleanSpaces( - tag.description - ) }`, + ( tag ) => { + return `\n- ${ getTypeOutput( tag ) }: ${ cleanSpaces( + `${ tag.name } ${ tag.description }` + ) }`; + }, docs ); formatTag( 'Type Definition', getSymbolTagsByName( symbol, 'typedef' ), - ( tag ) => `\n- *${ tag.name }* ${ getTypeOutput( tag.type ) }`, + ( tag ) => `\n- *${ tag.name }* ${ getTypeOutput( tag ) }`, docs ); formatTag( @@ -144,7 +153,7 @@ module.exports = ( getSymbolTagsByName( symbol, 'property' ), ( tag ) => `\n- *${ tag.name }* ${ getTypeOutput( - tag.type + tag ) }: ${ cleanSpaces( tag.description ) }`, docs ); diff --git a/packages/docgen/package.json b/packages/docgen/package.json index 1923fbdfc6fed7..db3efb48801e5b 100644 --- a/packages/docgen/package.json +++ b/packages/docgen/package.json @@ -28,7 +28,7 @@ }, "dependencies": { "@babel/core": "^7.12.9", - "doctrine": "^2.1.0", + "comment-parser": "^1.1.1", "lodash": "^4.17.19", "mdast-util-inject": "1.1.0", "optionator": "0.8.2", diff --git a/packages/docgen/test/fixtures/default-parse-error/code.js b/packages/docgen/test/fixtures/default-parse-error/code.js index 7ee4848213c63c..e547f397035133 100644 --- a/packages/docgen/test/fixtures/default-parse-error/code.js +++ b/packages/docgen/test/fixtures/default-parse-error/code.js @@ -1,3 +1,4 @@ +/* eslint-disable jsdoc/valid-types */ /** * Function invoking callback after delay with current timestamp in milliseconds * since epoch. @@ -7,3 +8,4 @@ export default function invokeCallbackAfterDelay( callback ) { setTimeout( () => callback( Date.now() ), 1000 ); } +/* eslint-enable jsdoc/valid-types */ diff --git a/packages/docgen/test/fixtures/default-parse-error/exports.json b/packages/docgen/test/fixtures/default-parse-error/exports.json index 04e396cc1fc436..8000aef1e6b73a 100644 --- a/packages/docgen/test/fixtures/default-parse-error/exports.json +++ b/packages/docgen/test/fixtures/default-parse-error/exports.json @@ -1 +1 @@ -[{"type":"ExportDefaultDeclaration","start":173,"end":288,"loc":{"start":{"line":7,"column":0},"end":{"line":9,"column":1}},"range":[173,288],"declaration":{"type":"FunctionDeclaration","start":188,"end":288,"loc":{"start":{"line":7,"column":15},"end":{"line":9,"column":1}},"range":[188,288],"id":{"type":"Identifier","start":197,"end":221,"loc":{"start":{"line":7,"column":24},"end":{"line":7,"column":48}},"range":[197,221],"name":"invokeCallbackAfterDelay"},"generator":false,"expression":false,"async":false,"params":[{"type":"Identifier","start":223,"end":231,"loc":{"start":{"line":7,"column":50},"end":{"line":7,"column":58}},"range":[223,231],"name":"callback"}],"body":{"type":"BlockStatement","start":234,"end":288,"loc":{"start":{"line":7,"column":61},"end":{"line":9,"column":1}},"range":[234,288],"body":[{"type":"ExpressionStatement","start":237,"end":286,"loc":{"start":{"line":8,"column":1},"end":{"line":8,"column":50}},"range":[237,286],"expression":{"type":"CallExpression","start":237,"end":285,"loc":{"start":{"line":8,"column":1},"end":{"line":8,"column":49}},"range":[237,285],"callee":{"type":"Identifier","start":237,"end":247,"loc":{"start":{"line":8,"column":1},"end":{"line":8,"column":11}},"range":[237,247],"name":"setTimeout"},"arguments":[{"type":"ArrowFunctionExpression","start":249,"end":277,"loc":{"start":{"line":8,"column":13},"end":{"line":8,"column":41}},"range":[249,277],"id":null,"generator":false,"expression":true,"async":false,"params":[],"body":{"type":"CallExpression","start":255,"end":277,"loc":{"start":{"line":8,"column":19},"end":{"line":8,"column":41}},"range":[255,277],"callee":{"type":"Identifier","start":255,"end":263,"loc":{"start":{"line":8,"column":19},"end":{"line":8,"column":27}},"range":[255,263],"name":"callback"},"arguments":[{"type":"CallExpression","start":265,"end":275,"loc":{"start":{"line":8,"column":29},"end":{"line":8,"column":39}},"range":[265,275],"callee":{"type":"MemberExpression","start":265,"end":273,"loc":{"start":{"line":8,"column":29},"end":{"line":8,"column":37}},"range":[265,273],"object":{"type":"Identifier","start":265,"end":269,"loc":{"start":{"line":8,"column":29},"end":{"line":8,"column":33}},"range":[265,269],"name":"Date"},"property":{"type":"Identifier","start":270,"end":273,"loc":{"start":{"line":8,"column":34},"end":{"line":8,"column":37}},"range":[270,273],"name":"now"},"computed":false},"arguments":[]}]}},{"type":"Literal","start":279,"end":283,"loc":{"start":{"line":8,"column":43},"end":{"line":8,"column":47}},"range":[279,283],"value":1000,"raw":"1000"}]}}]}},"leadingComments":[{"type":"Block","value":"*\n * Function invoking callback after delay with current timestamp in milliseconds\n * since epoch.\n *\n * @param {(timestamp:number)=>void} callback Callback function.\n ","start":0,"end":172,"range":[0,172],"loc":{"start":{"line":1,"column":0},"end":{"line":6,"column":3}}}]}] +[{"type":"ExportDefaultDeclaration","start":173,"end":288,"loc":{"start":{"line":7,"column":0},"end":{"line":9,"column":1}},"range":[173,288],"declaration":{"type":"FunctionDeclaration","start":188,"end":288,"loc":{"start":{"line":7,"column":15},"end":{"line":9,"column":1}},"range":[188,288],"id":{"type":"Identifier","start":197,"end":221,"loc":{"start":{"line":7,"column":24},"end":{"line":7,"column":48}},"range":[197,221],"name":"invokeCallbackAfterDelay"},"generator":false,"expression":false,"async":false,"params":[{"type":"Identifier","start":223,"end":231,"loc":{"start":{"line":7,"column":50},"end":{"line":7,"column":58}},"range":[223,231],"name":"callback"}],"body":{"type":"BlockStatement","start":234,"end":288,"loc":{"start":{"line":7,"column":61},"end":{"line":9,"column":1}},"range":[234,288],"body":[{"type":"ExpressionStatement","start":237,"end":286,"loc":{"start":{"line":8,"column":1},"end":{"line":8,"column":50}},"range":[237,286],"expression":{"type":"CallExpression","start":237,"end":285,"loc":{"start":{"line":8,"column":1},"end":{"line":8,"column":49}},"range":[237,285],"callee":{"type":"Identifier","start":237,"end":247,"loc":{"start":{"line":8,"column":1},"end":{"line":8,"column":11}},"range":[237,247],"name":"setTimeout"},"arguments":[{"type":"ArrowFunctionExpression","start":249,"end":277,"loc":{"start":{"line":8,"column":13},"end":{"line":8,"column":41}},"range":[249,277],"id":null,"generator":false,"expression":true,"async":false,"params":[],"body":{"type":"CallExpression","start":255,"end":277,"loc":{"start":{"line":8,"column":19},"end":{"line":8,"column":41}},"range":[255,277],"callee":{"type":"Identifier","start":255,"end":263,"loc":{"start":{"line":8,"column":19},"end":{"line":8,"column":27}},"range":[255,263],"name":"callback"},"arguments":[{"type":"CallExpression","start":265,"end":275,"loc":{"start":{"line":8,"column":29},"end":{"line":8,"column":39}},"range":[265,275],"callee":{"type":"MemberExpression","start":265,"end":273,"loc":{"start":{"line":8,"column":29},"end":{"line":8,"column":37}},"range":[265,273],"object":{"type":"Identifier","start":265,"end":269,"loc":{"start":{"line":8,"column":29},"end":{"line":8,"column":33}},"range":[265,269],"name":"Date"},"property":{"type":"Identifier","start":270,"end":273,"loc":{"start":{"line":8,"column":34},"end":{"line":8,"column":37}},"range":[270,273],"name":"now"},"computed":false},"arguments":[]}]}},{"type":"Literal","start":279,"end":283,"loc":{"start":{"line":8,"column":43},"end":{"line":8,"column":47}},"range":[279,283],"value":1000,"raw":"1000"}]}}]}},"leadingComments":[{"type":"Block","value":"*\n * Function invoking callback after delay with current timestamp in milliseconds\n * since epoch.\n *\n * @param {(timestamp:number=>void} callback Callback function.\n ","start":0,"end":172,"range":[0,172],"loc":{"start":{"line":1,"column":0},"end":{"line":6,"column":3}}}]}] diff --git a/packages/docgen/test/formatter-markdown.js b/packages/docgen/test/formatter-markdown.js index ee16487056c5c4..eedad6bf018cf3 100644 --- a/packages/docgen/test/formatter-markdown.js +++ b/packages/docgen/test/formatter-markdown.js @@ -16,14 +16,15 @@ describe( 'Formatter', () => { description: 'My declaration example.', tags: [ { - title: 'param', + tag: 'param', description: 'First declaration parameter.', type: 'number', name: 'firstParam', }, { - title: 'return', - description: 'The result of the declaration.', + tag: 'return', + name: 'The', + description: 'result of the declaration.', type: 'number', }, ], @@ -38,36 +39,4 @@ describe( 'Formatter', () => { '# API docs\n\n# **myDeclaration**\n\nMy declaration example.\n\n*Parameters*\n\n- *firstParam* `number`: First declaration parameter.\n\n*Returns*\n\n- `number`: The result of the declaration.\n' ); } ); - - it( 'handles unknown types from parse error', () => { - const rootDir = '/home/my-path'; - const docPath = '/home/my-path/docs'; - const docs = formatter( - rootDir, - docPath + '-api.md', - [ - { - path: null, - name: 'default', - description: - 'Function invoking callback after delay with current timestamp in milliseconds\nsince epoch.', - tags: [ - { - description: 'Callback function.', - errors: [ 'unexpected token' ], - name: 'callback', - title: 'param', - type: null, - }, - ], - lineStart: 7, - lineEnd: 9, - }, - ], - 'API docs' - ); - expect( docs ).toBe( - '# API docs\n\n# **default**\n\nFunction invoking callback after delay with current timestamp in milliseconds\nsince epoch.\n\n*Parameters*\n\n- *callback* (unknown type): Callback function.\n' - ); - } ); } ); diff --git a/packages/docgen/test/get-intermediate-representation.js b/packages/docgen/test/get-intermediate-representation.js index c33fdc771af46d..8e2bca25793f92 100644 --- a/packages/docgen/test/get-intermediate-representation.js +++ b/packages/docgen/test/get-intermediate-representation.js @@ -50,37 +50,6 @@ describe( 'Intermediate Representation', () => { } ); } ); - it( 'type parse error handling', () => { - const token = JSON.parse( - fs.readFileSync( - path.join( - __dirname, - './fixtures/default-parse-error/exports.json' - ), - 'utf-8' - ) - )[ 0 ]; - const ir = getIntermediateRepresentation( null, token ); - expect( ir ).toHaveLength( 1 ); - expect( ir[ 0 ] ).toEqual( { - path: null, - name: 'default', - description: - 'Function invoking callback after delay with current timestamp in milliseconds\nsince epoch.', - tags: [ - { - description: 'Callback function.', - errors: [ 'unexpected token' ], - name: 'callback', - title: 'param', - type: null, - }, - ], - lineStart: 7, - lineEnd: 9, - } ); - } ); - describe( 'JSDoc in export statement', () => { it( 'default export', () => { const tokenClassAnonymous = fs.readFileSync( diff --git a/packages/docgen/test/get-jsdoc-from-token.js b/packages/docgen/test/get-jsdoc-from-token.js index 414530affd68e8..13f7b21bcdc13a 100644 --- a/packages/docgen/test/get-jsdoc-from-token.js +++ b/packages/docgen/test/get-jsdoc-from-token.js @@ -14,46 +14,49 @@ describe( 'JSDoc', () => { }, ], } ) - ).toEqual( { - description: 'A function that adds two parameters.', + ).toMatchObject( { + description: 'A function that adds two parameters.\n', tags: [ { - title: 'deprecated', - description: 'Use native addition instead.', + tag: 'deprecated', + name: 'Use', + description: 'native addition instead.', }, { - title: 'since', - description: 'v2', + tag: 'since', + name: 'v2', }, { - title: 'see', - description: 'addition', + tag: 'see', + name: 'addition', }, { - title: 'link', - description: + tag: 'link', + name: 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators', }, { - title: 'param', + tag: 'param', description: 'The first param to add.', type: 'number', name: 'firstParam', + optional: false, }, { - title: 'param', - description: 'The second param to add.', + tag: 'param', + description: 'The second param to add.\n', type: 'number', name: 'secondParam', }, { - title: 'example', + tag: 'example', description: - '```js\nconst addResult = sum( 1, 3 );\nconsole.log( addResult ); // will yield 4\n```', + ' \n\n```js\nconst addResult = sum( 1, 3 );\nconsole.log( addResult ); // will yield 4\n```\n', }, { - title: 'return', - description: 'The result of adding the two params.', + tag: 'return', + name: 'The', + description: 'result of adding the two params.', type: 'number', }, ], @@ -68,13 +71,14 @@ describe( 'JSDoc', () => { }, ], } ) - ).toEqual( { + ).toMatchObject( { description: - 'Constant to document the meaning of life,\nthe universe and everything else.', + 'Constant to document the meaning of life,\nthe universe and everything else.\n', tags: [ { - title: 'type', - description: null, + tag: 'type', + name: '', + description: '', type: 'number', }, ], @@ -89,18 +93,21 @@ describe( 'JSDoc', () => { }, ], } ) - ).toEqual( { + ).toMatchObject( { description: 'Function invoking callback after delay with current timestamp in milliseconds since epoch.', tags: [ { - title: 'param', - errors: [ 'unexpected token' ], + tag: 'param', description: 'Callback function.', name: 'callback', - type: null, + type: '(timestamp:number)=>void', }, ], } ); + + expect( + getJSDocFromToken( { leadingComments: [ { value: '' } ] } ) + ).toBeUndefined(); } ); } ); diff --git a/packages/dom/README.md b/packages/dom/README.md index c26a0ae99da445..7baf10c94d8358 100644 --- a/packages/dom/README.md +++ b/packages/dom/README.md @@ -84,7 +84,7 @@ _Parameters_ _Returns_ -- `Array`: An array containing all files. +- `Object[]`: An array containing all files. # **getOffsetParent** diff --git a/packages/e2e-test-utils/README.md b/packages/e2e-test-utils/README.md index f5e50b4deb30e1..55e162ac6bec3a 100644 --- a/packages/e2e-test-utils/README.md +++ b/packages/e2e-test-utils/README.md @@ -188,9 +188,9 @@ Deletes a theme from the site, activating another theme if necessary. _Parameters_ - _slug_ `string`: Theme slug. -- _settings_ `?Object`: Optional settings object. -- _settings.newThemeSlug_ `?string`: A theme to switch to if the theme to delete is active. Required if the theme to delete is active. -- _settings.newThemeSearchTerm_ `?string`: A search term to use if the new theme is not findable by its slug. +- _settings_ `Object?`: Optional settings object. +- _settings.newThemeSlug_ `string?`: A theme to switch to if the theme to delete is active. Required if the theme to delete is active. +- _settings.newThemeSearchTerm_ `string?`: A search term to use if the new theme is not findable by its slug. # **disableFocusLossObservation** @@ -259,7 +259,7 @@ _Parameters_ _Returns_ -- `Promise<(ElementHandle|undefined)>`: Object that represents an in-page DOM element. +- `Promise`: Object that represents an in-page DOM element. # **getAllBlockInserterItemTitles** @@ -383,7 +383,7 @@ Installs a plugin from the WP.org repository. _Parameters_ - _slug_ `string`: Plugin slug. -- _searchTerm_ `?string`: If the plugin is not findable by its slug use an alternative term to search. +- _searchTerm_ `string?`: If the plugin is not findable by its slug use an alternative term to search. # **installTheme** @@ -392,8 +392,8 @@ Installs a theme from the WP.org repository. _Parameters_ - _slug_ `string`: Theme slug. -- _settings_ `?Object`: Optional settings object. -- _settings.searchTerm_ `?string`: Search term to use if the theme is not findable by its slug. +- _settings_ `Object?`: Optional settings object. +- _settings.searchTerm_ `string?`: Search term to use if the theme is not findable by its slug. # **isCurrentURL** @@ -450,7 +450,7 @@ _Parameters_ - _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_ @@ -677,8 +677,8 @@ Navigates to the post listing screen and bulk-trashes any posts which exist. _Parameters_ -- _postType_ `string`: String slug for type of post to trash. -- _postStatus_ `string`: String status of posts to trash. +- _postType_ `string`: - String slug for type of post to trash. +- _postStatus_ `string`: - String status of posts to trash. _Returns_ diff --git a/packages/edit-post/src/components/block-settings-menu/plugin-block-settings-menu-item.js b/packages/edit-post/src/components/block-settings-menu/plugin-block-settings-menu-item.js index 5f8712b3611f47..6005fe7bab85f1 100644 --- a/packages/edit-post/src/components/block-settings-menu/plugin-block-settings-menu-item.js +++ b/packages/edit-post/src/components/block-settings-menu/plugin-block-settings-menu-item.js @@ -40,7 +40,6 @@ const shouldRenderItem = ( selectedBlocks, allowedBlocks ) => * @param {string} [props.role] The ARIA role for the menu item. * * @example - * ES5 * ```js * // Using ES5 syntax * var __ = wp.i18n.__; @@ -64,7 +63,6 @@ const shouldRenderItem = ( selectedBlocks, allowedBlocks ) => * ``` * * @example - * ESNext * ```jsx * // Using ESNext syntax * import { __ } from '@wordpress/i18n'; diff --git a/packages/edit-post/src/components/header/plugin-more-menu-item/index.js b/packages/edit-post/src/components/header/plugin-more-menu-item/index.js index 2d55772447885b..ab6957931e458a 100644 --- a/packages/edit-post/src/components/header/plugin-more-menu-item/index.js +++ b/packages/edit-post/src/components/header/plugin-more-menu-item/index.js @@ -16,7 +16,6 @@ import { withPluginContext } from '@wordpress/plugins'; * @param {...*} [props.other] Any additional props are passed through to the underlying [MenuItem](/packages/components/src/menu-item/README.md) component. * * @example - * ES5 * ```js * // Using ES5 syntax * var __ = wp.i18n.__; @@ -40,7 +39,6 @@ import { withPluginContext } from '@wordpress/plugins'; * ``` * * @example - * ESNext * ```jsx * // Using ESNext syntax * import { __ } from '@wordpress/i18n'; diff --git a/packages/edit-post/src/components/header/plugin-sidebar-more-menu-item/index.js b/packages/edit-post/src/components/header/plugin-sidebar-more-menu-item/index.js index 2ed29f7f8d8c39..b1a3a7c00fef41 100644 --- a/packages/edit-post/src/components/header/plugin-sidebar-more-menu-item/index.js +++ b/packages/edit-post/src/components/header/plugin-sidebar-more-menu-item/index.js @@ -13,7 +13,6 @@ import { ComplementaryAreaMoreMenuItem } from '@wordpress/interface'; * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. * * @example - * ES5 * ```js * // Using ES5 syntax * var __ = wp.i18n.__; @@ -33,7 +32,6 @@ import { ComplementaryAreaMoreMenuItem } from '@wordpress/interface'; * ``` * * @example - * ESNext * ```jsx * // Using ESNext syntax * import { __ } from '@wordpress/i18n'; diff --git a/packages/edit-post/src/components/sidebar/plugin-document-setting-panel/index.js b/packages/edit-post/src/components/sidebar/plugin-document-setting-panel/index.js index b7ceebd3031f5d..e3f768798cb2ea 100644 --- a/packages/edit-post/src/components/sidebar/plugin-document-setting-panel/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-document-setting-panel/index.js @@ -62,7 +62,6 @@ const PluginDocumentSettingFill = ( { * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. * * @example - * ES5 * ```js * // Using ES5 syntax * var el = wp.element.createElement; @@ -87,7 +86,6 @@ const PluginDocumentSettingFill = ( { * ``` * * @example - * ESNext * ```jsx * // Using ESNext syntax * import { registerPlugin } from '@wordpress/plugins'; diff --git a/packages/edit-post/src/components/sidebar/plugin-post-publish-panel/index.js b/packages/edit-post/src/components/sidebar/plugin-post-publish-panel/index.js index 5a54525cf5ca20..ee05ff954e5e37 100644 --- a/packages/edit-post/src/components/sidebar/plugin-post-publish-panel/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-post-publish-panel/index.js @@ -36,7 +36,6 @@ const PluginPostPublishPanelFill = ( { * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. * * @example - * ES5 * ```js * // Using ES5 syntax * var __ = wp.i18n.__; @@ -56,7 +55,6 @@ const PluginPostPublishPanelFill = ( { * ``` * * @example - * ESNext * ```jsx * // Using ESNext syntax * import { __ } from '@wordpress/i18n'; diff --git a/packages/edit-post/src/components/sidebar/plugin-post-status-info/index.js b/packages/edit-post/src/components/sidebar/plugin-post-status-info/index.js index 18208485ddea24..3afc6b2c599563 100644 --- a/packages/edit-post/src/components/sidebar/plugin-post-status-info/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-post-status-info/index.js @@ -19,7 +19,6 @@ export const { Fill, Slot } = createSlotFill( 'PluginPostStatusInfo' ); * @param {WPElement} props.children Children to be rendered. * * @example - * ES5 * ```js * // Using ES5 syntax * var __ = wp.i18n.__; @@ -37,7 +36,6 @@ export const { Fill, Slot } = createSlotFill( 'PluginPostStatusInfo' ); * ``` * * @example - * ESNext * ```jsx * // Using ESNext syntax * import { __ } from '@wordpress/i18n'; diff --git a/packages/edit-post/src/components/sidebar/plugin-pre-publish-panel/index.js b/packages/edit-post/src/components/sidebar/plugin-pre-publish-panel/index.js index 7eedb60103ba40..b5912df3d498c9 100644 --- a/packages/edit-post/src/components/sidebar/plugin-pre-publish-panel/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-pre-publish-panel/index.js @@ -39,7 +39,6 @@ const PluginPrePublishPanelFill = ( { * the sidebar is pinned to toolbar. * * @example - * ES5 * ```js * // Using ES5 syntax * var __ = wp.i18n.__; @@ -59,7 +58,6 @@ const PluginPrePublishPanelFill = ( { * ``` * * @example - * ESNext * ```jsx * // Using ESNext syntax * import { __ } from '@wordpress/i18n'; diff --git a/packages/edit-post/src/components/sidebar/plugin-sidebar/index.js b/packages/edit-post/src/components/sidebar/plugin-sidebar/index.js index b1f6cb517145ad..390d407486c039 100644 --- a/packages/edit-post/src/components/sidebar/plugin-sidebar/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-sidebar/index.js @@ -29,7 +29,6 @@ import { store as editPostStore } from '../../../store'; * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. * * @example - * ES5 * ```js * // Using ES5 syntax * var __ = wp.i18n.__; @@ -56,7 +55,6 @@ import { store as editPostStore } from '../../../store'; * ``` * * @example - * ESNext * ```jsx * // Using ESNext syntax * import { __ } from '@wordpress/i18n'; diff --git a/packages/element/README.md b/packages/element/README.md index c1f819f6116f5f..3c355b5472dafd 100755 --- a/packages/element/README.md +++ b/packages/element/README.md @@ -180,7 +180,7 @@ _Related_ _Parameters_ -- _child_ (unknown type): Any renderable child, such as an element, string, or fragment. +- _child_ `import('./react').WPElement`: Any renderable child, such as an element, string, or fragment. - _container_ `HTMLElement`: DOM node into which element should be rendered. # **createRef** @@ -199,7 +199,7 @@ Finds the dom node of a React component. _Parameters_ -- _component_ (unknown type): Component's instance. +- _component_ `import('./react').WPComponent`: Component's instance. # **forwardRef** @@ -265,9 +265,7 @@ This is the same concept as the React Native implementation. _Related_ -- - -Here is an example of how to use the select method: +- Here is an example of how to use the select method: _Usage_ @@ -301,7 +299,7 @@ Renders a given element into the target DOM node. _Parameters_ -- _element_ (unknown type): Element to render. +- _element_ `import('./react').WPElement`: Element to render. - _target_ `HTMLElement`: DOM node into which element should be rendered. # **renderToString** @@ -310,7 +308,7 @@ Serializes a React element to string. _Parameters_ -- _element_ (unknown type): Element to serialize. +- _element_ `import('react').ReactNode`: Element to serialize. - _context_ `[Object]`: Context object. - _legacyContext_ `[Object]`: Legacy context object. diff --git a/packages/escape-html/README.md b/packages/escape-html/README.md index 6f112276748131..8d9f451d3403af 100644 --- a/packages/escape-html/README.md +++ b/packages/escape-html/README.md @@ -43,10 +43,8 @@ Returns an escaped attribute value. _Related_ -- - -"[...] the text cannot contain an ambiguous ampersand [...] must not contain -any literal U+0022 QUOTATION MARK characters (")" +- "[...] the text cannot contain an ambiguous ampersand [...] must not contain + any literal U+0022 QUOTATION MARK characters (")" Note we also escape the greater than symbol, as this is used by wptexturize to split HTML strings. This is a WordPress specific fix @@ -84,10 +82,8 @@ Returns an escaped HTML element value. _Related_ -- - -"the text must not contain the character U+003C LESS-THAN SIGN (\<) or an -ambiguous ampersand." +- "the text must not contain the character U+003C LESS-THAN SIGN (\<) or an + ambiguous ampersand." _Parameters_ diff --git a/packages/keycodes/README.md b/packages/keycodes/README.md index eb82e9e64abe1e..a4dfdcd1682d10 100644 --- a/packages/keycodes/README.md +++ b/packages/keycodes/README.md @@ -88,7 +88,7 @@ displayShortcutList.primary( 'm' ); _Type_ -- `WPModifierHandler>>` Keyed map of functions to shortcut sequences. +- `WPModifierHandler>` Keyed map of functions to shortcut sequences. # **DOWN** @@ -134,7 +134,7 @@ depending on platform. _Type_ -- (unknown type) +- `WPModifierHandler< ( isApple: () => boolean ) => WPModifierPart[]>` # **rawShortcut** diff --git a/packages/plugins/README.md b/packages/plugins/README.md index ebcca8c3f5c2fc..915033f0be40c3 100644 --- a/packages/plugins/README.md +++ b/packages/plugins/README.md @@ -34,7 +34,7 @@ Returns all registered plugins. _Returns_ -- `Array`: Plugin settings. +- `WPPlugin[]`: Plugin settings. # **PluginArea** diff --git a/packages/plugins/src/api/index.js b/packages/plugins/src/api/index.js index 8a844b311cefda..2ba66f7f5716aa 100644 --- a/packages/plugins/src/api/index.js +++ b/packages/plugins/src/api/index.js @@ -42,7 +42,6 @@ const plugins = {}; * @param {WPPlugin} settings The settings for this plugin. * * @example - * ES5 * ```js * // Using ES5 syntax * var el = wp.element.createElement; @@ -80,7 +79,6 @@ const plugins = {}; * ``` * * @example - * ESNext * ```js * // Using ESNext syntax * import { PluginSidebar, PluginSidebarMoreMenuItem } from '@wordpress/edit-post'; @@ -156,7 +154,6 @@ export function registerPlugin( name, settings ) { * @param {string} name Plugin name. * * @example - * ES5 * ```js * // Using ES5 syntax * var unregisterPlugin = wp.plugins.unregisterPlugin; @@ -165,7 +162,6 @@ export function registerPlugin( name, settings ) { * ``` * * @example - * ESNext * ```js * // Using ESNext syntax * import { unregisterPlugin } from '@wordpress/plugins'; diff --git a/packages/plugins/src/components/plugin-area/index.js b/packages/plugins/src/components/plugin-area/index.js index 4caa4827cfd485..2eef49a149dd0d 100644 --- a/packages/plugins/src/components/plugin-area/index.js +++ b/packages/plugins/src/components/plugin-area/index.js @@ -19,7 +19,6 @@ import { getPlugins } from '../../api'; * A component that renders all plugin fills in a hidden div. * * @example - * ES5 * ```js * // Using ES5 syntax * var el = wp.element.createElement; @@ -36,7 +35,6 @@ import { getPlugins } from '../../api'; * ``` * * @example - * ESNext * ```js * // Using ESNext syntax * import { PluginArea } from '@wordpress/plugins'; diff --git a/packages/react-i18n/README.md b/packages/react-i18n/README.md index f0065bbd03dd21..3ba4cfc473b38d 100644 --- a/packages/react-i18n/README.md +++ b/packages/react-i18n/README.md @@ -74,11 +74,11 @@ export default withI18n( MyComponent ); _Parameters_ -- _InnerComponent_ (unknown type): React component to be wrapped and receive the i18n functions like `__` +- _InnerComponent_ ``: React component to be wrapped and receive the i18n functions like `__` _Returns_ -- (unknown type): The wrapped component +- ``: The wrapped component diff --git a/packages/rich-text/README.md b/packages/rich-text/README.md index effb098201fd56..8f0fc331b27c83 100644 --- a/packages/rich-text/README.md +++ b/packages/rich-text/README.md @@ -105,7 +105,7 @@ _Parameters_ _Returns_ -- `(RichTextFormat|undefined)`: Active format object of the specified type, or undefined. +- `RichTextFormat|undefined`: Active format object of the specified type, or undefined. # **getActiveObject** @@ -117,7 +117,7 @@ _Parameters_ _Returns_ -- `(RichTextFormat|void)`: Active object, or undefined. +- `RichTextFormat|void`: Active object, or undefined. # **getTextContent** @@ -142,7 +142,7 @@ none are provided. _Parameters_ - _value_ `RichTextValue`: Value to modify. -- _valueToInsert_ `(RichTextValue|string)`: Value to insert. +- _valueToInsert_ `RichTextValue|string`: Value to insert. - _startIndex_ `[number]`: Start index. - _endIndex_ `[number]`: End index. @@ -180,7 +180,7 @@ _Parameters_ _Returns_ -- `(boolean|undefined)`: True if the selection is collapsed, false if not, undefined if there is no selection. +- `boolean|undefined`: True if the selection is collapsed, false if not, undefined if there is no selection. # **isEmpty** @@ -204,7 +204,7 @@ string. This is similar to `Array.prototype.join`. _Parameters_ - _values_ `Array`: An array of values to join. -- _separator_ `[(string|RichTextValue)]`: Separator string or value. +- _separator_ `[string|RichTextValue]`: Separator string or value. _Returns_ @@ -222,7 +222,7 @@ _Parameters_ _Returns_ -- `(WPFormat|undefined)`: The format, if it has been successfully registered; otherwise `undefined`. +- `WPFormat|undefined`: The format, if it has been successfully registered; otherwise `undefined`. # **remove** @@ -264,8 +264,8 @@ is similar to `String.prototype.replace`. _Parameters_ - _value_ `RichTextValue`: The value to modify. -- _pattern_ `(RegExp|string)`: A RegExp object or literal. Can also be a string. It is treated as a verbatim string and is not interpreted as a regular expression. Only the first occurrence will be replaced. -- _replacement_ `(Function|string)`: The match or matches are replaced with the specified or the value returned by the specified function. +- _pattern_ `RegExp|string`: A RegExp object or literal. Can also be a string. It is treated as a verbatim string and is not interpreted as a regular expression. Only the first occurrence will be replaced. +- _replacement_ `Function|string`: The match or matches are replaced with the specified or the value returned by the specified function. _Returns_ @@ -296,7 +296,7 @@ Indices are retrieved from the selection if none are provided. _Parameters_ - _value_ `RichTextValue`: -- _string_ `[(number|string)]`: Start index, or string at which to split. +- _string_ `[number|string]`: Start index, or string at which to split. _Returns_ @@ -353,7 +353,7 @@ _Parameters_ _Returns_ -- `(RichTextFormatType|undefined)`: The previous format value, if it has been successfully unregistered; otherwise `undefined`. +- `RichTextFormatType|undefined`: The previous format value, if it has been successfully unregistered; otherwise `undefined`. # **useAnchorRef** @@ -371,7 +371,7 @@ _Parameters_ _Returns_ -- `(Element|Range)`: The active element or selection range. +- `Element|Range`: The active element or selection range. diff --git a/packages/url/README.md b/packages/url/README.md index d369f6ed7cd62d..84d5aa67961ead 100644 --- a/packages/url/README.md +++ b/packages/url/README.md @@ -102,7 +102,7 @@ const imageUrl = filterURLForDisplay( 'https://www.wordpress.org/wp-content/uplo _Parameters_ - _url_ `string`: Original URL. -- _maxLength_ `(number|null)`: URL length. +- _maxLength_ `number|null`: URL length. _Returns_ @@ -125,7 +125,7 @@ _Parameters_ _Returns_ -- `(string|void)`: The authority part of the URL. +- `string|void`: The authority part of the URL. # **getFragment** @@ -144,7 +144,7 @@ _Parameters_ _Returns_ -- `(string|void)`: The fragment part of the URL. +- `string|void`: The fragment part of the URL. # **getPath** @@ -163,7 +163,7 @@ _Parameters_ _Returns_ -- `(string|void)`: The path part of the URL. +- `string|void`: The path part of the URL. # **getPathAndQueryString** @@ -201,7 +201,7 @@ _Parameters_ _Returns_ -- `(string|void)`: The protocol part of the URL. +- `string|void`: The protocol part of the URL. # **getQueryArg** @@ -220,7 +220,7 @@ _Parameters_ _Returns_ -- `(QueryArgParsed|void)`: Query arg value. +- `QueryArgParsed|void`: Query arg value. # **getQueryArgs** @@ -258,7 +258,7 @@ _Parameters_ _Returns_ -- `(string|void)`: The query string part of the URL. +- `string|void`: The query string part of the URL. # **hasQueryArg**