diff --git a/blocks/api/categories.js b/blocks/api/categories.js index 3844c38263a10..2a76e170cb378 100644 --- a/blocks/api/categories.js +++ b/blocks/api/categories.js @@ -21,7 +21,7 @@ const categories = [ ]; /** - * Returns all the block categories + * Returns all the block categories. * * @returns {Array} Block categories. */ diff --git a/blocks/api/factory.js b/blocks/api/factory.js index 43d8c488e72d0..eec7e77aa7358 100644 --- a/blocks/api/factory.js +++ b/blocks/api/factory.js @@ -30,8 +30,8 @@ import { getBlockType, getBlockTypes } from './registration'; /** * Returns a block object given its type and attributes. * - * @param {String} name Block name - * @param {Object} blockAttributes Block attributes + * @param {string} name Block name. + * @param {Object} blockAttributes Block attributes. * * @returns {Object} Block object. */ @@ -63,11 +63,12 @@ export function createBlock( name, blockAttributes = {} ) { } /** - * Returns a predicate that receives a transformation and returns true if the given - * transformation is able to execute in the situation specified in the params + * Returns a predicate that receives a transformation and returns true if the + * given transformation is able to execute in the situation specified in the + * params. * - * @param {String} sourceName Block name - * @param {Boolean} isMultiBlock Array of possible block transformations + * @param {string} sourceName Block name. + * @param {boolean} isMultiBlock Array of possible block transformations. * * @returns {Function} Predicate that receives a block type. */ @@ -78,11 +79,12 @@ const isTransformForBlockSource = ( sourceName, isMultiBlock = false ) => ( tran ); /** - * Returns a predicate that receives a block type and returns true if the given block type contains a - * transformation able to execute in the situation specified in the params + * Returns a predicate that receives a block type and returns true if the given + * block type contains a transformation able to execute in the situation + * specified in the params. * - * @param {String} sourceName Block name - * @param {Boolean} isMultiBlock Array of possible block transformations + * @param {string} sourceName Block name. + * @param {boolean} isMultiBlock Array of possible block transformations. * * @returns {Function} Predicate that receives a block type. */ @@ -94,9 +96,10 @@ const createIsTypeTransformableFrom = ( sourceName, isMultiBlock = false ) => ( ); /** - * Returns an array of possible block transformations that could happen on the set of blocks received as argument. + * Returns an array of possible block transformations that could happen on the + * set of blocks received as argument. * - * @param {Array} blocks Blocks array + * @param {Array} blocks Blocks array. * * @returns {Array} Array of possible block transformations. */ @@ -143,8 +146,8 @@ export function getPossibleBlockTransformations( blocks ) { /** * Switch one or more blocks into one or more blocks of the new block type. * - * @param {Array|Object} blocks Blocks array or block object - * @param {string} name Block name + * @param {Array|Object} blocks Blocks array or block object. + * @param {string} name Block name. * * @returns {Array} Array of blocks. */ @@ -221,8 +224,10 @@ export function switchToBlockType( blocks, name ) { /** * Creates a new reusable block. * - * @param {String} type The type of the block referenced by the reusable block - * @param {Object} attributes The attributes of the block referenced by the reusable block + * @param {string} type The type of the block referenced by the reusable + * block. + * @param {Object} attributes The attributes of the block referenced by the + * reusable block. * * @returns {Object} A reusable block object. */ diff --git a/blocks/api/parser.js b/blocks/api/parser.js index 2de25032cb4be..2b34b2912505d 100644 --- a/blocks/api/parser.js +++ b/blocks/api/parser.js @@ -15,12 +15,12 @@ import { getCommentDelimitedContent } from './serializer'; import { attr, prop, html, text, query, node, children } from './matchers'; /** - * Returns value coerced to the specified JSON schema type string + * Returns value coerced to the specified JSON schema type string. * * @see http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.25 * - * @param {*} value Original value - * @param {String} type Type to coerce + * @param {*} value Original value. + * @param {string} type Type to coerce. * * @returns {*} Coerced value. */ @@ -54,11 +54,11 @@ export function asType( value, type ) { } /** - * Returns an hpq matcher given a source object + * Returns an hpq matcher given a source object. * - * @param {Object} sourceConfig Attribute Source object + * @param {Object} sourceConfig Attribute Source object. * - * @returns {Function} hpq Matcher. + * @returns {Function} A hpq Matcher. */ export function matcherFromSource( sourceConfig ) { switch ( sourceConfig.source ) { @@ -84,13 +84,14 @@ export function matcherFromSource( sourceConfig ) { } /** - * Given an attribute key, an attribute's schema, a block's raw content and the commentAttributes - * returns the attribute value depending on its source definition of the given attribute key + * Given an attribute key, an attribute's schema, a block's raw content and the + * commentAttributes returns the attribute value depending on its source + * definition of the given attribute key. * - * @param {string} attributeKey Attribute key - * @param {Object} attributeSchema Attribute's schema - * @param {string} innerHTML Block's raw content - * @param {Object} commentAttributes Block's comment attributes + * @param {string} attributeKey Attribute key. + * @param {Object} attributeSchema Attribute's schema. + * @param {string} innerHTML Block's raw content. + * @param {Object} commentAttributes Block's comment attributes. * * @returns {*} Attribute value. */ @@ -118,9 +119,9 @@ export function getBlockAttribute( attributeKey, attributeSchema, innerHTML, com /** * Returns the block attributes of a registered block node given its type. * - * @param {?Object} blockType Block type - * @param {string} innerHTML Raw block content - * @param {?Object} attributes Known block attributes (from delimiters) + * @param {?Object} blockType Block type. + * @param {string} innerHTML Raw block content. + * @param {?Object} attributes Known block attributes (from delimiters). * * @returns {Object} All block attributes. */ @@ -133,11 +134,12 @@ export function getBlockAttributes( blockType, innerHTML, attributes ) { } /** - * Attempt to parse the innerHTML using using a supplied `deprecated` definition. + * Attempt to parse the innerHTML using using a supplied `deprecated` + * definition. * - * @param {?Object} blockType Block type - * @param {string} innerHTML Raw block content - * @param {?Object} attributes Known block attributes (from delimiters) + * @param {?Object} blockType Block type. + * @param {string} innerHTML Raw block content. + * @param {?Object} attributes Known block attributes (from delimiters). * * @returns {Object} Block attributes. */ @@ -162,9 +164,9 @@ export function getAttributesFromDeprecatedVersion( blockType, innerHTML, attrib /** * Creates a block with fallback to the unknown type handler. * - * @param {?String} name Block type name - * @param {String} innerHTML Raw block content - * @param {?Object} attributes Attributes obtained from block delimiters + * @param {?String} name Block type name. + * @param {string} innerHTML Raw block content. + * @param {?Object} attributes Attributes obtained from block delimiters. * * @returns {?Object} An initialized block object (if possible). */ @@ -232,7 +234,7 @@ export function createBlockWithFallback( name, innerHTML, attributes ) { /** * Parses the post content with a PegJS grammar and returns a list of blocks. * - * @param {String} content The post content + * @param {string} content The post content. * * @returns {Array} Block list. */ diff --git a/blocks/api/raw-handling/index.js b/blocks/api/raw-handling/index.js index ccff345ba79ea..7fb5ed22bbb26 100644 --- a/blocks/api/raw-handling/index.js +++ b/blocks/api/raw-handling/index.js @@ -28,13 +28,14 @@ import shortcodeConverter from './shortcode-converter'; /** * Converts an HTML string to known blocks. Strips everything else. * - * @param {String} options.HTML The HTML to convert. - * @param {String} [options.plainText] Plain text version. - * @param {String} [options.mode] Handle content as blocks or inline content. - * * 'AUTO': Decide based on the content passed. - * * 'INLINE': Always handle as inline content, and return string. - * * 'BLOCKS': Always handle as blocks, and return array of blocks. - * @param {Array} [options.tagName] The tag into which content will be inserted. + * @param {string} [options.HTML] The HTML to convert. + * @param {string} [options.plainText] Plain text version. + * @param {string} [options.mode] Handle content as blocks or inline content. + * * 'AUTO': Decide based on the content passed. + * * 'INLINE': Always handle as inline content, and return string. + * * 'BLOCKS': Always handle as blocks, and return array of blocks. + * @param {Array} [options.tagName] The tag into which content will be + * inserted. * * @returns {Array|String} A list of blocks or a string, depending on `handlerMode`. */ diff --git a/blocks/api/raw-handling/utils.js b/blocks/api/raw-handling/utils.js index fd3678032d618..faa157c40fe6e 100644 --- a/blocks/api/raw-handling/utils.js +++ b/blocks/api/raw-handling/utils.js @@ -82,10 +82,10 @@ export function isAttributeWhitelisted( tag, attribute ) { * Checks if nodeName should be treated as inline when being added to tagName. * This happens if nodeName and tagName are in the same group defined in inlineWhitelistTagGroups. * - * @param {String} nodeName Node name. - * @param {String} tagName Tag name. + * @param {string} nodeName Node name. + * @param {string} tagName Tag name. * - * @returns {Boolean} True if nodeName is inline in the context of tagName and + * @returns {boolean} True if nodeName is inline in the context of tagName and * false otherwise. */ function isInlineForTag( nodeName, tagName ) { @@ -197,9 +197,9 @@ export function isPlain( HTML ) { /** * Given node filters, deeply filters and mutates a NodeList. * - * @param {NodeList} nodeList The nodeList to filter. - * @param {Array} filters An array of functions that can mutate with the provided node. - * @param {Document} doc The document of the nodeList. + * @param {NodeList} nodeList The nodeList to filter. + * @param {Array} filters An array of functions that can mutate with the provided node. + * @param {Document} doc The document of the nodeList. */ export function deepFilterNodeList( nodeList, filters, doc ) { Array.from( nodeList ).forEach( ( node ) => { @@ -219,10 +219,10 @@ export function deepFilterNodeList( nodeList, filters, doc ) { /** * Given node filters, deeply filters HTML tags. * - * @param {String} HTML The HTML to filter. - * @param {Array} filters An array of functions that can mutate with the provided node. + * @param {string} HTML The HTML to filter. + * @param {Array} filters An array of functions that can mutate with the provided node. * - * @returns {String} The filtered HTML. + * @returns {string} The filtered HTML. */ export function deepFilterHTML( HTML, filters = [] ) { const doc = document.implementation.createHTMLDocument( '' ); diff --git a/blocks/api/registration.js b/blocks/api/registration.js index 9723d38fdd3f1..0afbb701e5dcd 100644 --- a/blocks/api/registration.js +++ b/blocks/api/registration.js @@ -43,8 +43,8 @@ let defaultBlockName; * behavior. Once registered, the block is made available as an option to any * editor interface where blocks are implemented. * - * @param {string} name Block name - * @param {Object} settings Block settings + * @param {string} name Block name. + * @param {Object} settings Block settings. * * @returns {?WPBlock} The block, if it has been successfully registered; * otherwise `undefined`. @@ -128,7 +128,7 @@ export function registerBlockType( name, settings ) { /** * Unregisters a block. * - * @param {string} name Block name + * @param {string} name Block name. * * @returns {?WPBlock} The previous block value, if it has been successfully * unregistered; otherwise `undefined`. @@ -148,7 +148,7 @@ export function unregisterBlockType( name ) { /** * Assigns name of block handling unknown block types. * - * @param {string} name Block name + * @param {string} name Block name. */ export function setUnknownTypeHandlerName( name ) { unknownTypeHandlerName = name; @@ -165,16 +165,16 @@ export function getUnknownTypeHandlerName() { } /** - * Assigns the default block name + * Assigns the default block name. * - * @param {string} name Block name + * @param {string} name Block name. */ export function setDefaultBlockName( name ) { defaultBlockName = name; } /** - * Retrieves the default block name + * Retrieves the default block name. * * @returns {?string} Blog name. */ @@ -185,7 +185,7 @@ export function getDefaultBlockName() { /** * Returns a registered block type. * - * @param {string} name Block name + * @param {string} name Block name. * * @returns {?Object} Block type. */ @@ -203,14 +203,14 @@ export function getBlockTypes() { } /** - * Returns true if the block defines support for a feature, or false otherwise + * Returns true if the block defines support for a feature, or false otherwise. * - * @param {(String|Object)} nameOrType Block name or type object - * @param {String} feature Feature to test - * @param {Boolean} defaultSupports Whether feature is supported by - * default if not explicitly defined + * @param {(String|Object)} nameOrType Block name or type object. + * @param {string} feature Feature to test. + * @param {boolean} defaultSupports Whether feature is supported by + * default if not explicitly defined. * - * @returns {Boolean} Whether block supports feature. + * @returns {boolean} Whether block supports feature. */ export function hasBlockSupport( nameOrType, feature, defaultSupports ) { const blockType = 'string' === typeof nameOrType ? @@ -225,12 +225,12 @@ export function hasBlockSupport( nameOrType, feature, defaultSupports ) { /** * Determines whether or not the given block is a reusable block. This is a - * special block type that is used to point to a global block stored via the - * API. + * special block type that is used to point to a global block stored via + * the API. * - * @param {Object} blockOrType Block or Block Type to test + * @param {Object} blockOrType Block or Block Type to test. * - * @returns {Boolean} Whether the given block is a reusable block. + * @returns {boolean} Whether the given block is a reusable block. */ export function isReusableBlock( blockOrType ) { return blockOrType.name === 'core/block'; diff --git a/blocks/api/serializer.js b/blocks/api/serializer.js index a539058e0d254..29fc911efc255 100644 --- a/blocks/api/serializer.js +++ b/blocks/api/serializer.js @@ -16,9 +16,9 @@ import { applyFilters } from '@wordpress/hooks'; import { getBlockType, getUnknownTypeHandlerName } from './registration'; /** - * Returns the block's default classname from its name + * Returns the block's default classname from its name. * - * @param {String} blockName The block name + * @param {string} blockName The block name. * * @returns {string} The block's default class. */ @@ -31,8 +31,8 @@ export function getBlockDefaultClassname( blockName ) { * Given a block type containg a save render implementation and attributes, returns the * enhanced element to be saved or string when raw HTML expected. * - * @param {Object} blockType Block type - * @param {Object} attributes Block attributes + * @param {Object} blockType Block type. + * @param {Object} attributes Block attributes. * * @returns {Object|string} Save content. */ @@ -70,8 +70,8 @@ export function getSaveElement( blockType, attributes ) { * Given a block type containg a save render implementation and attributes, returns the * static markup to be saved. * - * @param {Object} blockType Block type - * @param {Object} attributes Block attributes + * @param {Object} blockType Block type. + * @param {Object} attributes Block attributes. * * @returns {string} Save content. */ @@ -98,8 +98,8 @@ export function getSaveContent( blockType, attributes ) { * This function returns only those attributes which are needed to persist and * which cannot be matched from the block content. * - * @param {Object} allAttributes Attributes from in-memory block data - * @param {Object} blockType Block type + * @param {Object} allAttributes Attributes from in-memory block data. + * @param {Object} blockType Block type. * * @returns {Object} Subset of attributes for comment serialization. */ @@ -143,9 +143,9 @@ export function serializeAttributes( attrs ) { * Returns HTML markup processed by a markup beautifier configured for use in * block serialization. * - * @param {String} content Original HTML + * @param {string} content Original HTML. * - * @returns {String} Beautiful HTML. + * @returns {string} Beautiful HTML. */ export function getBeautifulContent( content ) { return beautifyHtml( content, { @@ -155,10 +155,11 @@ export function getBeautifulContent( content ) { } /** - * Given a block object, returns the Block's Inner HTML markup - * @param {Object} block Block Object + * Given a block object, returns the Block's Inner HTML markup. * - * @returns {String} HTML. + * @param {Object} block Block Object. + * + * @returns {string} HTML. */ export function getBlockContent( block ) { const blockType = getBlockType( block.name ); @@ -178,11 +179,11 @@ export function getBlockContent( block ) { /** * Returns the content of a block, including comment delimiters. * - * @param {String} rawBlockName Block name - * @param {Object} attributes Block attributes - * @param {String} content Block save content + * @param {string} rawBlockName Block name. + * @param {Object} attributes Block attributes. + * @param {string} content Block save content. * - * @returns {String} Comment-delimited block content. + * @returns {string} Comment-delimited block content. */ export function getCommentDelimitedContent( rawBlockName, attributes, content ) { const serializedAttributes = ! isEmpty( attributes ) ? @@ -209,9 +210,9 @@ export function getCommentDelimitedContent( rawBlockName, attributes, content ) * Returns the content of a block, including comment delimiters, determining * serialized attributes and content form from the current state of the block. * - * @param {Object} block Block instance + * @param {Object} block Block instance. * - * @returns {String} Serialized block. + * @returns {string} Serialized block. */ export function serializeBlock( block ) { const blockName = block.name; @@ -244,9 +245,9 @@ export function serializeBlock( block ) { /** * Takes a block or set of blocks and returns the serialized post content. * - * @param {Array} blocks Block(s) to serialize + * @param {Array} blocks Block(s) to serialize. * - * @returns {String} The post content. + * @returns {string} The post content. */ export default function serialize( blocks ) { return castArray( blocks ).map( serializeBlock ).join( '\n\n' ); diff --git a/blocks/api/validation.js b/blocks/api/validation.js index 511462d3e2160..bcf33ca810158 100644 --- a/blocks/api/validation.js +++ b/blocks/api/validation.js @@ -132,7 +132,7 @@ const log = ( () => { /** * Creates a logger with block validation prefix. * - * @param {Function} logger Original logger function + * @param {Function} logger Original logger function. * * @returns {Function} Augmented logger function. */ @@ -160,7 +160,7 @@ const log = ( () => { * Given a specified string, returns an array of strings split by consecutive * whitespace, ignoring leading or trailing whitespace. * - * @param {String} text Original text + * @param {string} text Original text. * * @returns {String[]} Text pieces split on whitespace. */ @@ -172,9 +172,9 @@ export function getTextPiecesSplitOnWhitespace( text ) { * Given a specified string, returns a new trimmed string where all consecutive * whitespace is collapsed to a single space. * - * @param {String} text Original text + * @param {string} text Original text. * - * @returns {String} Trimmed text with consecutive whitespace collapsed. + * @returns {string} Trimmed text with consecutive whitespace collapsed. */ export function getTextWithCollapsedWhitespace( text ) { return getTextPiecesSplitOnWhitespace( text ).join( ' ' ); @@ -187,7 +187,7 @@ export function getTextWithCollapsedWhitespace( text ) { * * @see MEANINGFUL_ATTRIBUTES * - * @param {Object} token StartTag token + * @param {Object} token StartTag token. * * @returns {Array[]} Attribute pairs. */ @@ -206,10 +206,10 @@ export function getMeaningfulAttributePairs( token ) { * Returns true if two text tokens (with `chars` property) are equivalent, or * false otherwise. * - * @param {Object} actual Actual token - * @param {Object} expected Expected token + * @param {Object} actual Actual token. + * @param {Object} expected Expected token. * - * @returns {Boolean} Whether two text tokens are equivalent. + * @returns {boolean} Whether two text tokens are equivalent. */ export function isEqualTextTokensWithCollapsedWhitespace( actual, expected ) { // This is an overly simplified whitespace comparison. The specification is @@ -229,9 +229,9 @@ export function isEqualTextTokensWithCollapsedWhitespace( actual, expected ) { * Given a style value, returns a normalized style value for strict equality * comparison. * - * @param {String} value Style value + * @param {string} value Style value. * - * @returns {String} Normalized style value. + * @returns {string} Normalized style value. */ export function getNormalizedStyleValue( value ) { return value @@ -242,7 +242,7 @@ export function getNormalizedStyleValue( value ) { /** * Given a style attribute string, returns an object of style properties. * - * @param {String} text Style attribute + * @param {string} text Style attribute. * * @returns {Object} Style properties. */ @@ -285,12 +285,12 @@ export const isEqualAttributesOfName = { /** * Given two sets of attribute tuples, returns true if the attribute sets are - * equivalent + * equivalent. * - * @param {Array[]} actual Actual attributes tuples - * @param {Array[]} expected Expected attributes tuples + * @param {Array[]} actual Actual attributes tuples. + * @param {Array[]} expected Expected attributes tuples. * - * @returns {Boolean} Whether attributes are equivalent. + * @returns {boolean} Whether attributes are equivalent. */ export function isEqualTagAttributePairs( actual, expected ) { // Attributes is tokenized as tuples. Their lengths should match. This also @@ -357,7 +357,7 @@ export const isEqualTokensOfType = { * * Mutates the tokens array. * - * @param {Object[]} tokens Set of tokens to search + * @param {Object[]} tokens Set of tokens to search. * * @returns {Object} Next non-whitespace token. */ @@ -378,10 +378,10 @@ export function getNextNonWhitespaceToken( tokens ) { * Returns true if there is given HTML strings are effectively equivalent, or * false otherwise. * - * @param {String} actual Actual HTML string - * @param {String} expected Expected HTML string + * @param {string} actual Actual HTML string. + * @param {string} expected Expected HTML string. * - * @returns {Boolean} Whether HTML strings are equivalent. + * @returns {boolean} Whether HTML strings are equivalent. */ export function isEquivalentHTML( actual, expected ) { // Tokenize input content and reserialized save content @@ -428,11 +428,11 @@ export function isEquivalentHTML( actual, expected ) { * * Logs to console in development environments when invalid. * - * @param {String} innerHTML Original block content - * @param {String} blockType Block type - * @param {Object} attributes Parsed block attributes + * @param {string} innerHTML Original block content. + * @param {string} blockType Block type. + * @param {Object} attributes Parsed block attributes. * - * @returns {Boolean} Whether block is valid. + * @returns {boolean} Whether block is valid. */ export function isValidBlock( innerHTML, blockType, attributes ) { let saveContent; diff --git a/blocks/autocompleters/index.js b/blocks/autocompleters/index.js index d7e92a3e992fa..8775e8a63c64a 100644 --- a/blocks/autocompleters/index.js +++ b/blocks/autocompleters/index.js @@ -61,7 +61,7 @@ import BlockIcon from '../block-icon'; * Returns an "completer" definition for selecting from available blocks to replace the current one. * The definition can be understood by the Autocomplete component. * - * @param {Function} onReplace Callback to replace the current block. + * @param {Function} onReplace Callback to replace the current block. * * @returns {Completer} Completer object used by the Autocomplete component. */ diff --git a/blocks/editable/index.js b/blocks/editable/index.js index a225c4162b2db..3657ae0ae839a 100644 --- a/blocks/editable/index.js +++ b/blocks/editable/index.js @@ -126,7 +126,7 @@ export default class Editable extends Component { } /** - * Handles the onSetup event for the tinyMCE component + * Handles the onSetup event for the tinyMCE component. * * Will setup event handlers for the tinyMCE instance. * An `onSetup` function in the props will be called if it is present. @@ -160,15 +160,15 @@ export default class Editable extends Component { } /** - * Allows prop event handlers to handle an event + * Allows prop event handlers to handle an event. * - * Allow props an opportunity to handle the event, before default - * Editable behavior takes effect. Should the event be handled by a - * prop, it should `stopImmediatePropagation` on the event to stop - * continued event handling. + * Allow props an opportunity to handle the event, before default Editable + * behavior takes effect. Should the event be handled by a prop, it should + * `stopImmediatePropagation` on the event to stop continued event handling. * * @param {string} name The name of the event. - * @returns {void} + * + * @returns {void} Void. */ proxyPropHandler( name ) { return ( event ) => { @@ -253,7 +253,7 @@ export default class Editable extends Component { } /** - * Handles an undo event from tinyMCE + * Handles an undo event from tinyMCE. * * When user attempts Undo when empty Undo stack, propagate undo * action to context handler. The compromise here is that: TinyMCE @@ -276,7 +276,7 @@ export default class Editable extends Component { } /** - * Handles a paste event from tinyMCE + * Handles a paste event from tinyMCE. * * Saves the pasted data as plain text in `pastedPlainText`. * @@ -319,12 +319,14 @@ export default class Editable extends Component { } /** - * Handles a PrePasteProcess event from tinyMCE + * Handles a PrePasteProcess event from tinyMCE. * * Will call the paste handler with the pasted data. If it is a string tries - * to put it in the containing tinyMCE editor. Otherwise call the `onSplit` handler. + * to put it in the containing tinyMCE editor. Otherwise call the `onSplit` + * handler. * - * @param {PrePasteProcessEvent} event The PrePasteProcess event as triggered by tinyMCE. + * @param {PrePasteProcessEvent} event The PrePasteProcess event as triggered + * by tinyMCE. */ onPastePreProcess( event ) { const HTML = this.isPlainTextPaste ? this.pastedPlainText : event.content; @@ -519,7 +521,7 @@ export default class Editable extends Component { } /** - * Handles a keydown event from tinyMCE + * Handles a keydown event from tinyMCE. * * @param {KeydownEvent} event The keydow event as triggered by tinyMCE. */ @@ -592,7 +594,7 @@ export default class Editable extends Component { } /** - * Handles tinyMCE key up event + * Handles tinyMCE key up event. * * @param {number} keyCode The key code that has been pressed on the keyboard. */ diff --git a/blocks/hooks/anchor.js b/blocks/hooks/anchor.js index 71ea806285795..ae284ed97f158 100644 --- a/blocks/hooks/anchor.js +++ b/blocks/hooks/anchor.js @@ -25,9 +25,9 @@ const ANCHOR_REGEX = /[\s#]/g; /** * Filters registered block settings, extending attributes with anchor using ID - * of the first node + * of the first node. * - * @param {Object} settings Original block settings + * @param {Object} settings Original block settings. * * @returns {Object} Filtered block settings. */ @@ -51,9 +51,9 @@ 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. * - * @returns {function} Wrapped component. + * @returns {string} Wrapped component. */ export function withInspectorControl( BlockEdit ) { const WrappedBlockEdit = ( props ) => { @@ -85,9 +85,9 @@ export function withInspectorControl( BlockEdit ) { * supports anchor. This is only applied if the block's save result is an * element and not a markup string. * - * @param {Object} extraProps Additional props applied to save element - * @param {Object} blockType Block type - * @param {Object} attributes Current block attributes + * @param {Object} extraProps Additional props applied to save element. + * @param {Object} blockType Block type. + * @param {Object} attributes Current block attributes. * * @returns {Object} Filtered props applied to save element. */ diff --git a/blocks/hooks/custom-class-name.js b/blocks/hooks/custom-class-name.js index 0e025c1da79ce..29de5ca933895 100644 --- a/blocks/hooks/custom-class-name.js +++ b/blocks/hooks/custom-class-name.js @@ -19,9 +19,9 @@ import InspectorControls from '../inspector-controls'; /** * Filters registered block settings, extending attributes with anchor using ID - * of the first node + * of the first node. * - * @param {Object} settings Original block settings + * @param {Object} settings Original block settings. * * @returns {Object} Filtered block settings. */ @@ -42,9 +42,9 @@ 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. * - * @returns {function} Wrapped component. + * @returns {string} Wrapped component. */ export function withInspectorControl( BlockEdit ) { const WrappedBlockEdit = ( props ) => { @@ -75,9 +75,9 @@ export function withInspectorControl( BlockEdit ) { * supports anchor. This is only applied if the block's save result is an * element and not a markup string. * - * @param {Object} extraProps Additional props applied to save element - * @param {Object} blockType Block type - * @param {Object} attributes Current block attributes + * @param {Object} extraProps Additional props applied to save element. + * @param {Object} blockType Block type. + * @param {Object} attributes Current block attributes. * * @returns {Object} Filtered props applied to save element. */ diff --git a/blocks/hooks/generated-class-name.js b/blocks/hooks/generated-class-name.js index ef1d87f64e4d9..28083b591add2 100644 --- a/blocks/hooks/generated-class-name.js +++ b/blocks/hooks/generated-class-name.js @@ -14,12 +14,12 @@ import { addFilter } from '@wordpress/hooks'; import { hasBlockSupport, getBlockDefaultClassname } from '../api'; /** - * Override props assigned to save component to inject generated className if block - * supports it. This is only applied if the block's save result is an + * Override props assigned to save component to inject generated className if + * block supports it. This is only applied if the block's save result is an * element and not a markup string. * - * @param {Object} extraProps Additional props applied to save element - * @param {Object} blockType Block type + * @param {Object} extraProps Additional props applied to save element. + * @param {Object} blockType Block type. * * @returns {Object} Filtered props applied to save element. */ diff --git a/blocks/hooks/matchers.js b/blocks/hooks/matchers.js index 6f277fd2ce0df..3dbc88ff66a97 100644 --- a/blocks/hooks/matchers.js +++ b/blocks/hooks/matchers.js @@ -76,9 +76,9 @@ export const node = ( selector ) => () => { }; /** - * Resolve the matchers attributes for backwards compatibilty + * Resolve the matchers attributes for backwards compatibilty. * - * @param {Object} settings Original block settings + * @param {Object} settings Original block settings. * * @returns {Object} Filtered block settings. */ diff --git a/blocks/media-upload/index.js b/blocks/media-upload/index.js index f83b75fa46db0..287b999770059 100644 --- a/blocks/media-upload/index.js +++ b/blocks/media-upload/index.js @@ -19,7 +19,7 @@ const getGalleryDetailsMediaFrame = () => { /** * Create the default states. * - * @returns {void} + * @returns {void} Void. */ createStates: function createStates() { this.states.add( [ diff --git a/components/autocomplete/index.js b/components/autocomplete/index.js index 7792c86b9a005..7d249c38e4c19 100644 --- a/components/autocomplete/index.js +++ b/components/autocomplete/index.js @@ -25,9 +25,10 @@ const { ENTER, ESCAPE, UP, DOWN, LEFT, RIGHT, SPACE } = keycodes; /** * Recursively select the firstChild until hitting a leaf node. - * @param {Node} node the node to find the recursive first child. * - * @returns {Node} the first leaf-node >= node in the ordering. + * @param {Node} node The node to find the recursive first child. + * + * @returns {Node} The first leaf-node >= node in the ordering. */ function descendFirst( node ) { let n = node; @@ -39,9 +40,10 @@ function descendFirst( node ) { /** * Recursively select the lastChild until hitting a leaf node. - * @param {Node} node the node to find the recursive last child. * - * @returns {Node} the first leaf-node <= node in the ordering. + * @param {Node} node The node to find the recursive last child. + * + * @returns {Node} The first leaf-node <= node in the ordering. */ function descendLast( node ) { let n = node; @@ -53,9 +55,10 @@ function descendLast( node ) { /** * Is the node a text node. - * @param {?Node} node the node to check. * - * @returns {boolean} true if the node is a text node. + * @param {?Node} node The node to check. + * + * @returns {boolean} True if the node is a text node. */ function isTextNode( node ) { return node !== null && node.nodeType === 3; @@ -63,9 +66,10 @@ function isTextNode( node ) { /** * Return the node only if it is a text node, otherwise return null. - * @param {?Node} node the node to filter. * - * @returns {?Node} the node or null if it is not a text node. + * @param {?Node} node The node to filter. + * + * @returns {?Node} The node or null if it is not a text node. */ function onlyTextNode( node ) { return isTextNode( node ) ? node : null; @@ -73,9 +77,10 @@ function onlyTextNode( node ) { /** * Find the index of the last charater in the text that is whitespace. - * @param {String} text the text to search. * - * @returns {Number} the last index of a white space character in the text or -1. + * @param {string} text The text to search. + * + * @returns {number} The last index of a white space character in the text or -1. */ function lastIndexOfSpace( text ) { for ( let i = text.length - 1; i >= 0; i-- ) { diff --git a/components/autocomplete/test/index.js b/components/autocomplete/test/index.js index ce7fa009707cd..505ba6e62fea9 100644 --- a/components/autocomplete/test/index.js +++ b/components/autocomplete/test/index.js @@ -53,19 +53,20 @@ function makeAutocompleter( completers, AutocompleteComponent = Autocomplete ) { } /** - * Create a text node - * @param {String} text text of text node. + * Create a text node. + * + * @param {string} text Text of text node. - * @returns {Node} a text node. + * @returns {Node} A text node. */ function tx( text ) { return document.createTextNode( text ); } /** - * Create a paragraph node with the arguments as children + * Create a paragraph node with the arguments as children. - * @returns {Node} a paragraph node. + * @returns {Node} A paragraph node. */ function par( /* arguments */ ) { const p = document.createElement( 'p' ); @@ -77,9 +78,12 @@ function par( /* arguments */ ) { * Simulate typing into the fake editor by updating the content and simulating * an input event. It also updates the data-cursor attribute which is used to * simulate the cursor position in the test mocks. - * @param {*} wrapper enzyme wrapper around react node containing a FakeEditor. - * @param {Array.} nodeList array of dom nodes. - * @param {Array.} cursorPosition array specifying the child indexes and offset of the cursor + * + * @param {*} wrapper Enzyme wrapper around react node + * containing a FakeEditor. + * @param {Array.} nodeList Array of dom nodes. + * @param {Array.} cursorPosition Array specifying the child indexes and + * offset of the cursor. */ function simulateInput( wrapper, nodeList, cursorPosition ) { // update the editor content @@ -100,8 +104,10 @@ function simulateInput( wrapper, nodeList, cursorPosition ) { /** * Fire a native keydown event on the fake editor in the wrapper. - * @param {*} wrapper the wrapper containing the FakeEditor where the event will be dispatched. - * @param {*} keyCode the keycode of the key event. + * + * @param {*} wrapper The wrapper containing the FakeEditor where the event will + * be dispatched. + * @param {*} keyCode The keycode of the key event. */ function simulateKeydown( wrapper, keyCode ) { const fakeEditor = wrapper.getDOMNode().querySelector( '.fake-editor' ); @@ -112,7 +118,8 @@ function simulateKeydown( wrapper, keyCode ) { /** * Check that the autocomplete matches the initial state. - * @param {*} wrapper the enzyme react wrapper. + * + * @param {*} wrapper The enzyme react wrapper. */ function expectInitialState( wrapper ) { expect( wrapper.state( 'open' ) ).toBeUndefined(); diff --git a/components/higher-order/with-api-data/request.js b/components/higher-order/with-api-data/request.js index 70747e693956e..d28a556a33952 100644 --- a/components/higher-order/with-api-data/request.js +++ b/components/higher-order/with-api-data/request.js @@ -45,7 +45,7 @@ export const cache = mapKeys( * * @see https://xhr.spec.whatwg.org/#the-getallresponseheaders()-method * - * @param {XMLHttpRequest} xhr XMLHttpRequest object + * @param {XMLHttpRequest} xhr XMLHttpRequest object. * * @returns {Array[]} Array of header tuples. */ @@ -64,7 +64,7 @@ export function getResponseHeaders( xhr ) { * Returns a response payload if GET request and a cached result exists, or * undefined otherwise. * - * @param {Object} request Request object (path, method) + * @param {Object} request Request object (path, method). * * @returns {?Object} Response object (body, headers). */ diff --git a/components/higher-order/with-api-data/routes.js b/components/higher-order/with-api-data/routes.js index c218cb2b0a2d4..0d51219c9cb07 100644 --- a/components/higher-order/with-api-data/routes.js +++ b/components/higher-order/with-api-data/routes.js @@ -20,7 +20,7 @@ const RE_NAMED_SUBPATTERN = /\(\?P?[<']\w+[>'](.*?)\)/g; * replacing named subpatterns (unsupported in JavaScript), allowing trailing * slash, allowing query parameters, but otherwise enforcing strict equality. * - * @param {String} pattern PCRE regular expression string + * @param {string} pattern PCRE regular expression string. * * @returns {RegExp} Equivalent JavaScript RegExp. */ @@ -33,10 +33,10 @@ export function getNormalizedRegExp( pattern ) { /** * Returns true if the route path pattern string matches the given path. * - * @param {String} pattern PCRE route path pattern - * @param {String} path URL path + * @param {string} pattern PCRE route path pattern. + * @param {string} path URL path. * - * @returns {Boolean} Whether path is a match. + * @returns {boolean} Whether path is a match. */ export function isRouteMatch( pattern, path ) { return getNormalizedRegExp( pattern ).test( path ); @@ -45,8 +45,8 @@ export function isRouteMatch( pattern, path ) { /** * Returns a REST route object for a given path, if one exists. * - * @param {Object} schema REST schema - * @param {String} path URL path + * @param {Object} schema REST schema. + * @param {string} path URL path. * * @returns {?Object} REST route. */ diff --git a/components/higher-order/with-filters/index.js b/components/higher-order/with-filters/index.js index 56ab88a7b75c7..b301afb6622d0 100644 --- a/components/higher-order/with-filters/index.js +++ b/components/higher-order/with-filters/index.js @@ -5,10 +5,11 @@ import { Component, getWrapperDisplayName } from '@wordpress/element'; import { applyFilters } from '@wordpress/hooks'; /** - * Creates a higher-order component which adds filtering capability to the wrapped component. - * Filters get applied when the original component is about to be mounted. + * Creates a higher-order component which adds filtering capability to the + * wrapped component. Filters get applied when the original component is about + * to be mounted. * - * @param {String} hookName Hook name exposed to be used by filters. + * @param {string} hookName Hook name exposed to be used by filters. * * @returns {Function} Higher-order component factory. */ diff --git a/components/higher-order/with-focus-return/index.js b/components/higher-order/with-focus-return/index.js index 9fc822117213a..dd521ca7c702e 100644 --- a/components/higher-order/with-focus-return/index.js +++ b/components/higher-order/with-focus-return/index.js @@ -4,11 +4,12 @@ import { Component } from '@wordpress/element'; /** - * Higher Order Component used to be used to wrap disposable elements like Sidebars, modals, dropdowns. - * When mounting the wrapped component, we track a reference to the current active element - * so we know where to restore focus when the component is unmounted + * Higher Order Component used to be used to wrap disposable elements like + * sidebars, modals, dropdowns. When mounting the wrapped component, we track a + * reference to the current active element so we know where to restore focus + * when the component is unmounted. * - * @param {WPElement} WrappedComponent The disposable component + * @param {WPElement} WrappedComponent The disposable component. * * @returns {Component} Component with the focus restauration behaviour. */ diff --git a/components/higher-order/with-instance-id/index.js b/components/higher-order/with-instance-id/index.js index dffd7abe9f05a..d35cb5cc0b307 100644 --- a/components/higher-order/with-instance-id/index.js +++ b/components/higher-order/with-instance-id/index.js @@ -4,9 +4,10 @@ import { Component } from '@wordpress/element'; /** - * A Higher Order Component used to be provide a unique instance ID by component + * A Higher Order Component used to be provide a unique instance ID by + * component. * - * @param {WPElement} WrappedComponent The wrapped component + * @param {WPElement} WrappedComponent The wrapped component. * * @returns {Component} Component with an instanceId prop. */ diff --git a/components/higher-order/with-spoken-messages/index.js b/components/higher-order/with-spoken-messages/index.js index 1930adcb5e833..4c16e216df2fd 100644 --- a/components/higher-order/with-spoken-messages/index.js +++ b/components/higher-order/with-spoken-messages/index.js @@ -10,9 +10,10 @@ import { Component } from '@wordpress/element'; import { speak } from '@wordpress/a11y'; /** - * A Higher Order Component used to be provide a unique instance ID by component + * A Higher Order Component used to be provide a unique instance ID by + * component. * - * @param {WPElement} WrappedComponent The wrapped component + * @param {WPElement} WrappedComponent The wrapped component. * * @returns {Component} Component with an instanceId prop. */ diff --git a/components/higher-order/with-state/index.js b/components/higher-order/with-state/index.js index dc5a3e537f55f..9e7595f357cc5 100644 --- a/components/higher-order/with-state/index.js +++ b/components/higher-order/with-state/index.js @@ -7,7 +7,7 @@ import { Component, getWrapperDisplayName } from '@wordpress/element'; * A Higher Order Component used to provide and manage internal component state * via props. * - * @param {?Object} initialState Optional initial state of the component + * @param {?Object} initialState Optional initial state of the component. * * @returns {Component} Wrapped component. */ diff --git a/components/tooltip/index.js b/components/tooltip/index.js index 89deb58a12b46..4ec47c248661d 100644 --- a/components/tooltip/index.js +++ b/components/tooltip/index.js @@ -59,9 +59,9 @@ class Tooltip extends Component { } /** - * Assigns DOM node of the rendered component as an instance property + * Assigns DOM node of the rendered component as an instance property. * - * @param {Element} ref Rendered component reference + * @param {Element} ref Rendered component reference. */ bindNode( ref ) { // Disable reason: Because render clones the child, we don't know what @@ -72,7 +72,7 @@ class Tooltip extends Component { } /** - * Disconnects any DOM observer attached to the rendered node + * Disconnects any DOM observer attached to the rendered node. */ disconnectDisabledAttributeObserver() { if ( this.observer ) { @@ -82,7 +82,7 @@ class Tooltip extends Component { /** * Adds a DOM observer to the rendered node, if supported and if the DOM - * node exists, to monitor for application of a disabled attribute + * node exists, to monitor for application of a disabled attribute. */ observeDisabledAttribute() { if ( ! window.MutationObserver || ! this.node ) { diff --git a/data/index.js b/data/index.js index 841b5263ac054..f0d14228bd1bd 100644 --- a/data/index.js +++ b/data/index.js @@ -21,10 +21,10 @@ const store = createStore( initialReducer, {}, flowRight( enhancers ) ); /** * Registers a new sub-reducer to the global state and returns a Redux-like store object. * - * @param {string} reducerKey Reducer key. - * @param {Object} reducer Reducer function. + * @param {string} reducerKey Reducer key. + * @param {Object} reducer Reducer function. * - * @returns {Object} Store Object. + * @returns {Object} Store Object. */ export function registerReducer( reducerKey, reducer ) { reducers[ reducerKey ] = reducer; @@ -52,11 +52,11 @@ export function registerReducer( reducerKey, reducer ) { /** * Registers selectors for external usage. * - * @param {string} reducerKey Part of the state shape to register the - * selectors for. - * @param {Object} newSelectors Selectors to register. Keys will be used - * as the public facing API. Selectors will - * get passed the state as first argument. + * @param {string} reducerKey Part of the state shape to register the + * selectors for. + * @param {Object} newSelectors Selectors to register. Keys will be used as the + * public facing API. Selectors will get passed the + * state as first argument. */ export function registerSelectors( reducerKey, newSelectors ) { selectors[ reducerKey ] = newSelectors; @@ -66,9 +66,10 @@ export function registerSelectors( reducerKey, newSelectors ) { * Higher Order Component used to inject data using the registered selectors. * * @param {Function} mapSelectorsToProps Gets called with the selectors object - * to determine the data for the component. + * to determine the data for the + * component. * - * @returns {Func} Renders the wrapped component and passes it data. + * @returns {Func} Renders the wrapped component and passes it data. */ export const query = ( mapSelectorsToProps ) => ( WrappedComponent ) => { const connectWithStore = ( ...args ) => { @@ -95,7 +96,7 @@ export const query = ( mapSelectorsToProps ) => ( WrappedComponent ) => { * @param {string} selectorName Selector name. * @param {*} args Selectors arguments. * - * @returns {*} The selector's returned value. + * @returns {*} The selector's returned value. */ export const select = ( reducerKey, selectorName, ...args ) => { return selectors[ reducerKey ][ selectorName ]( store.getState()[ reducerKey ], ...args ); diff --git a/date/index.js b/date/index.js index ab49f76326110..f8b7a83ee712f 100644 --- a/date/index.js +++ b/date/index.js @@ -221,10 +221,10 @@ function setupLocale( settings ) { /** * Formats a date. Does not alter the date's timezone. * - * @param {string} dateFormat PHP-style formatting string. - * See php.net/date - * @param {(Date|string|moment|null)} dateValue Date object or string, - * parsable by moment.js. + * @param {string} dateFormat PHP-style formatting string. + * See php.net/date. + * @param {(Date|string|moment|null)} dateValue Date object or string, + * parsable by moment.js. * * @returns {string} Formatted date. */ @@ -262,10 +262,10 @@ export function format( dateFormat, dateValue = new Date() ) { /** * Formats a date (like `date()` in PHP), in the site's timezone. * - * @param {string} dateFormat PHP-style formatting string. - * See php.net/date - * @param {(Date|string|moment|null)} dateValue Date object or string, - * parsable by moment.js. + * @param {string} dateFormat PHP-style formatting string. + * See php.net/date. + * @param {(Date|string|moment|null)} dateValue Date object or string, + * parsable by moment.js. * * @returns {string} Formatted date. */ @@ -278,10 +278,10 @@ export function date( dateFormat, dateValue = new Date() ) { /** * Formats a date (like `date()` in PHP), in the UTC timezone. * - * @param {string} dateFormat PHP-style formatting string. - * See php.net/date - * @param {(Date|string|moment|null)} dateValue Date object or string, - * parsable by moment.js. + * @param {string} dateFormat PHP-style formatting string. + * See php.net/date. + * @param {(Date|string|moment|null)} dateValue Date object or string, + * parsable by moment.js. * * @returns {string} Formatted date. */ @@ -293,12 +293,12 @@ export function gmdate( dateFormat, dateValue = new Date() ) { /** * Formats a date (like `dateI18n()` in PHP). * - * @param {string} dateFormat PHP-style formatting string. - * See php.net/date - * @param {(Date|string|moment|null)} dateValue Date object or string, - * parsable by moment.js. - * @param {boolean} gmt True for GMT/UTC, false for - * site's timezone. + * @param {string} dateFormat PHP-style formatting string. + * See php.net/date. + * @param {(Date|string|moment|null)} dateValue Date object or string, + * parsable by moment.js. + * @param {boolean} gmt True for GMT/UTC, false for + * site's timezone. * * @returns {string} Formatted date. */ diff --git a/editor/components/block-list/block.js b/editor/components/block-list/block.js index 7bc2f126e03cd..d057cf2ed8c93 100644 --- a/editor/components/block-list/block.js +++ b/editor/components/block-list/block.js @@ -70,7 +70,7 @@ const { BACKSPACE, ESCAPE, DELETE, ENTER, UP, RIGHT, DOWN, LEFT } = keycodes; /** * Given a DOM node, finds the closest scrollable container node. * - * @param {Element} node Node from which to start + * @param {Element} node Node from which to start. * * @returns {?Element} Scrollable container node, if found. */ diff --git a/editor/components/block-mover/mover-label.js b/editor/components/block-mover/mover-label.js index 2c0f2d7d5d3fc..4e8e9d8fca0fb 100644 --- a/editor/components/block-mover/mover-label.js +++ b/editor/components/block-mover/mover-label.js @@ -6,13 +6,13 @@ import { __, sprintf } from '@wordpress/i18n'; /** * Return a label for the block movement controls depending on block position. * - * @param {number} selectedCount Number of blocks selected. - * @param {string} type Block type - in the case of a single block, should + * @param {number} selectedCount Number of blocks selected. + * @param {string} type Block type - in the case of a single block, should * define its 'type'. I.e. 'Text', 'Heading', 'Image' etc. - * @param {number} firstIndex The index (position - 1) of the first block selected. - * @param {boolean} isFirst This is the first block. - * @param {boolean} isLast This is the last block. - * @param {number} dir Direction of movement (> 0 is considered to be going + * @param {number} firstIndex The index (position - 1) of the first block selected. + * @param {boolean} isFirst This is the first block. + * @param {boolean} isLast This is the last block. + * @param {number} dir Direction of movement (> 0 is considered to be going * down, < 0 is up). * * @returns {string} Label for the block movement controls. @@ -69,11 +69,11 @@ export function getBlockMoverLabel( selectedCount, type, firstIndex, isFirst, is /** * Return a label for the block movement controls depending on block position. * - * @param {number} selectedCount Number of blocks selected. - * @param {number} firstIndex The index (position - 1) of the first block selected. - * @param {boolean} isFirst This is the first block. - * @param {boolean} isLast This is the last block. - * @param {number} dir Direction of movement (> 0 is considered to be going + * @param {number} selectedCount Number of blocks selected. + * @param {number} firstIndex The index (position - 1) of the first block selected. + * @param {boolean} isFirst This is the first block. + * @param {boolean} isLast This is the last block. + * @param {number} dir Direction of movement (> 0 is considered to be going * down, < 0 is up). * * @returns {string} Label for the block movement controls. diff --git a/editor/index.js b/editor/index.js index 5e5f1115c3e65..35c3862a10036 100644 --- a/editor/index.js +++ b/editor/index.js @@ -38,7 +38,8 @@ if ( dateSettings.timezone.string ) { } /** - * Configure heartbeat to refresh the wp-api nonce, keeping the editor authorization intact. + * Configure heartbeat to refresh the wp-api nonce, keeping the editor + * authorization intact. */ window.jQuery( document ).on( 'heartbeat-tick', ( event, response ) => { if ( response[ 'rest-nonce' ] ) { @@ -51,8 +52,8 @@ window.jQuery( document ).on( 'heartbeat-tick', ( event, response ) => { * an unhandled error occurs, replacing previously mounted editor element using * an initial state from prior to the crash. * - * @param {Element} target DOM node in which editor is rendered - * @param {?Object} settings Editor settings object + * @param {Element} target DOM node in which editor is rendered. + * @param {?Object} settings Editor settings object. */ export function recreateEditorInstance( target, settings ) { unmountComponentAtNode( target ); @@ -75,9 +76,9 @@ export function recreateEditorInstance( target, settings ) { * The return value of this function is not necessary if we change where we * call createEditorInstance(). This is due to metaBox timing. * - * @param {String} id Unique identifier for editor instance - * @param {Object} post API entity for post to edit - * @param {?Object} settings Editor settings object + * @param {string} id Unique identifier for editor instance. + * @param {Object} post API entity for post to edit. + * @param {?Object} settings Editor settings object. * * @returns {Object} Editor interface. */ diff --git a/editor/store/actions.js b/editor/store/actions.js index 869bee2e9d65a..9529b00ac8ee3 100644 --- a/editor/store/actions.js +++ b/editor/store/actions.js @@ -8,8 +8,8 @@ import { partial, castArray } from 'lodash'; * Returns an action object used in signalling that editor has initialized with * the specified post object and editor settings. * - * @param {Object} post Post object - * @param {Object} settings Editor settings object + * @param {Object} post Post object. + * @param {Object} settings Editor settings object. * * @returns {Object} Action object. */ @@ -25,7 +25,7 @@ export function setupEditor( post, settings ) { * Returns an action object used in signalling that the latest version of the * post has been received, either by initialization or save. * - * @param {Object} post Post object + * @param {Object} post Post object. * * @returns {Object} Action object. */ @@ -40,7 +40,7 @@ export function resetPost( post ) { * Returns an action object used in signalling that editor has initialized as a * new post with specified edits which should be considered non-dirtying. * - * @param {Object} edits Edited attributes object + * @param {Object} edits Edited attributes object. * * @returns {Object} Action object. */ @@ -56,7 +56,7 @@ export function setupNewPost( edits ) { * reset to the specified array of blocks, taking precedence over any other * content reflected as an edit in state. * - * @param {Array} blocks Array of blocks + * @param {Array} blocks Array of blocks. * * @returns {Object} Action object. */ @@ -68,11 +68,11 @@ export function resetBlocks( blocks ) { } /** - * Returns an action object used in signalling that the block attributes with the - * specified UID has been updated. + * Returns an action object used in signalling that the block attributes with + * the specified UID has been updated. * - * @param {String} uid Block UID - * @param {Object} attributes Block attributes to be merged + * @param {string} uid Block UID. + * @param {Object} attributes Block attributes to be merged. * * @returns {Object} Action object. */ @@ -88,8 +88,8 @@ export function updateBlockAttributes( uid, attributes ) { * Returns an action object used in signalling that the block with the * specified UID has been updated. * - * @param {String} uid Block UID - * @param {Object} updates Block attributes to be merged + * @param {string} uid Block UID. + * @param {Object} updates Block attributes to be merged. * * @returns {Object} Action object. */ @@ -143,9 +143,10 @@ export function clearSelectedBlock() { } /** - * Returns an action object that enables or disables block selection + * Returns an action object that enables or disables block selection. * - * @param {boolean} [isSelectionEnabled=true] Whether block selection should be enabled + * @param {boolean} [isSelectionEnabled=true] Whether block selection should + * be enabled. * @returns {Object} Action object. */ @@ -160,8 +161,8 @@ export function toggleSelection( isSelectionEnabled = true ) { * Returns an action object signalling that a blocks should be replaced with * one or more replacement blocks. * - * @param {(String|String[])} uids Block UID(s) to replace - * @param {(Object|Object[])} blocks Replacement block(s) + * @param {(String|String[])} uids Block UID(s) to replace. + * @param {(Object|Object[])} blocks Replacement block(s). * * @returns {Object} Action object. */ @@ -177,8 +178,8 @@ export function replaceBlocks( uids, blocks ) { * Returns an action object signalling that a single block should be replaced * with one or more replacement blocks. * - * @param {(String|String[])} uid Block UID(s) to replace - * @param {(Object|Object[])} block Replacement block(s) + * @param {(String|String[])} uid Block UID(s) to replace. + * @param {(Object|Object[])} block Replacement block(s). * * @returns {Object} Action object. */ @@ -199,9 +200,9 @@ export function insertBlocks( blocks, position ) { } /** - * Returns an action object showing the insertion point at a given index + * Returns an action object showing the insertion point at a given index. * - * @param {Number?} index Index of the insertion point + * @param {Number?} index Index of the insertion point. * * @returns {Object} Action object. */ @@ -213,7 +214,7 @@ export function showInsertionPoint( index ) { } /** - * Returns an action object hiding the insertion point + * Returns an action object hiding the insertion point. * * @returns {Object} Action object. */ @@ -285,7 +286,7 @@ export function undo() { * Returns an action object used in signalling that the blocks * corresponding to the specified UID set are to be removed. * - * @param {String[]} uids Block UIDs + * @param {string[]} uids Block UIDs. * * @returns {Object} Action object. */ @@ -300,7 +301,7 @@ export function removeBlocks( uids ) { * Returns an action object used in signalling that the block with the * specified UID is to be removed. * - * @param {String} uid Block UID + * @param {string} uid Block UID. * * @returns {Object} Action object. */ @@ -309,9 +310,9 @@ export function removeBlock( uid ) { } /** - * Returns an action object used to toggle the block editing mode (visual/html) + * Returns an action object used to toggle the block editing mode (visual/html). * - * @param {String} uid Block UID + * @param {string} uid Block UID. * * @returns {Object} Action object. */ @@ -345,10 +346,12 @@ export function stopTyping() { } /** - * Returns an action object used in signalling that the user toggled the sidebar + * Returns an action object used in signalling that the user toggled the + * sidebar. * - * @param {String} sidebar Name of the sidebar to toggle (desktop, mobile or publish) - * @param {Boolean?} forcedValue Force a sidebar state + * @param {string} sidebar Name of the sidebar to toggle + * (desktop, mobile or publish). + * @param {Boolean?} forcedValue Force a sidebar state. * * @returns {Object} Action object. */ @@ -361,9 +364,10 @@ export function toggleSidebar( sidebar, forcedValue ) { } /** - * Returns an action object used in signalling that the user switched the active sidebar tab panel + * Returns an action object used in signalling that the user switched the active + * sidebar tab panel. * - * @param {String} panel The panel name + * @param {string} panel The panel name. * * @returns {Object} Action object. */ @@ -375,9 +379,10 @@ export function setActivePanel( panel ) { } /** - * Returns an action object used in signalling that the user toggled a sidebar panel + * Returns an action object used in signalling that the user toggled a + * sidebar panel. * - * @param {String} panel The panel name + * @param {string} panel The panel name. * * @returns {Object} Action object. */ @@ -389,13 +394,13 @@ export function toggleSidebarPanel( panel ) { } /** - * Returns an action object used to create a notice + * Returns an action object used to create a notice. * - * @param {String} status The notice status - * @param {WPElement} content The notice content - * @param {?Object} options The notice options. Available options: + * @param {string} status The notice status. + * @param {WPElement} content The notice content. + * @param {?Object} options The notice options. Available options: * `id` (string; default auto-generated) - * `isDismissible` (boolean; default `true`) + * `isDismissible` (boolean; default `true`). * * @returns {Object} Action object. */ @@ -418,9 +423,9 @@ export function createNotice( status, content, options = {} ) { } /** - * Returns an action object used to remove a notice + * Returns an action object used to remove a notice. * - * @param {String} id The notice id + * @param {string} id The notice id. * * @returns {Object} Action object. */ @@ -438,7 +443,8 @@ export function removeNotice( id ) { * area is empty, this will set the store state to indicate that React should * not render the meta box area. * - * Example: metaBoxes = { side: true, normal: false } + * Example: metaBoxes = { side: true, normal: false }. + * * This indicates that the sidebar has a meta box but the normal area does not. * * @param {Object} metaBoxes Whether meta box locations are active. @@ -455,7 +461,8 @@ export function initializeMetaBoxState( metaBoxes ) { /** * Returns an action object used to signify that a meta box finished reloading. * - * @param {String} location Location of meta box: 'normal', 'side' or 'advanced'. + * @param {string} location Location of meta box: 'normal', 'side' + * or 'advanced'. * * @returns {Object} Action object. */ @@ -469,7 +476,8 @@ export function handleMetaBoxReload( location ) { /** * Returns an action object used to signify that a meta box finished loading. * - * @param {String} location Location of meta box: 'normal', 'side' or 'advanced'. + * @param {string} location Location of meta box: 'normal', 'side' + * or 'advanced'. * * @returns {Object} Action object. */ @@ -483,7 +491,8 @@ export function metaBoxLoaded( location ) { /** * Returns an action object used to request meta box update. * - * @param {Array} locations Locations of meta boxes: ['normal', 'side', 'advanced' ]. + * @param {Array} locations Locations of meta boxes: ['normal', 'side', + * 'advanced' ]. * * @returns {Object} Action object. */ @@ -497,8 +506,9 @@ export function requestMetaBoxUpdates( locations ) { /** * Returns an action object used to set meta box state changed. * - * @param {String} location Location of meta box: 'normal', 'side' or 'advanced'. - * @param {Boolean} hasChanged Whether the meta box has changed. + * @param {string} location Location of meta box: 'normal', 'side' + * or 'advanced'. + * @param {boolean} hasChanged Whether the meta box has changed. * * @returns {Object} Action object. */ @@ -511,9 +521,9 @@ export function metaBoxStateChanged( location, hasChanged ) { } /** - * Returns an action object used to toggle a feature flag + * Returns an action object used to toggle a feature flag. * - * @param {String} feature Featurre name. + * @param {string} feature Featurre name. * * @returns {Object} Action object. */ @@ -533,7 +543,8 @@ export const createWarningNotice = partial( createNotice, 'warning' ); * Returns an action object used to fetch a single reusable block or all * reusable blocks from the REST API into the store. * - * @param {?string} id If given, only a single reusable block with this ID will be fetched + * @param {?string} id If given, only a single reusable block with this ID will + * be fetched. * * @returns {Object} Action object. */ @@ -545,10 +556,12 @@ export function fetchReusableBlocks( id ) { } /** - * Returns an action object used to insert or update a reusable block into the store. + * Returns an action object used to insert or update a reusable block into + * the store. * - * @param {Object} id The ID of the reusable block to update - * @param {Object} reusableBlock The new reusable block object. Any omitted keys are not changed + * @param {Object} id The ID of the reusable block to update. + * @param {Object} reusableBlock The new reusable block object. Any omitted keys + * are not changed. * * @returns {Object} Action object. */ @@ -564,7 +577,7 @@ export function updateReusableBlock( id, reusableBlock ) { * Returns an action object used to save a reusable block that's in the store * to the REST API. * - * @param {Object} id The ID of the reusable block to save + * @param {Object} id The ID of the reusable block to save. * * @returns {Object} Action object. */ @@ -578,7 +591,7 @@ export function saveReusableBlock( id ) { /** * Returns an action object used to delete a reusable block via the REST API. * - * @param {number} id The ID of the reusable block to delete. + * @param {number} id The ID of the reusable block to delete. * * @returns {Object} Action object. */ @@ -593,7 +606,7 @@ export function deleteReusableBlock( id ) { * Returns an action object used to convert a reusable block into a static * block. * - * @param {Object} uid The ID of the block to attach + * @param {Object} uid The ID of the block to attach. * * @returns {Object} Action object. */ @@ -608,7 +621,7 @@ export function convertBlockToStatic( uid ) { * Returns an action object used to convert a static block into a reusable * block. * - * @param {Object} uid The ID of the block to detach + * @param {Object} uid The ID of the block to detach. * * @returns {Object} Action object. */ diff --git a/editor/store/middlewares.js b/editor/store/middlewares.js index f1a4e0c593528..c0a8fef307bc1 100644 --- a/editor/store/middlewares.js +++ b/editor/store/middlewares.js @@ -12,9 +12,9 @@ import { mobileMiddleware } from '../utils/mobile'; import effects from './effects'; /** - * Applies the custom middlewares used specifically in the editor module + * Applies the custom middlewares used specifically in the editor module. * - * @param {Object} store Store Object + * @param {Object} store Store Object. * * @returns {Object} Update Store Object. */ diff --git a/editor/store/mobile.js b/editor/store/mobile.js index 4691d37a3f3dc..797ce3a3a96df 100644 --- a/editor/store/mobile.js +++ b/editor/store/mobile.js @@ -1,8 +1,8 @@ /** - * Enhance a redux store with the browser size + * Enhance a redux store with the browser size. * - * @param {Object} store Redux Store - * @param {Number} mobileBreakpoint The mobile breakpoint + * @param {Object} store Redux Store. + * @param {number} mobileBreakpoint The mobile breakpoint. */ function enhanceWithBrowserSize( store, mobileBreakpoint ) { const updateSize = () => { diff --git a/editor/store/persist.js b/editor/store/persist.js index 8c50f9c8b641c..f5de2cc4ae237 100644 --- a/editor/store/persist.js +++ b/editor/store/persist.js @@ -4,10 +4,10 @@ import { get } from 'lodash'; /** - * Adds the rehydratation behavior to redux reducers + * Adds the rehydratation behavior to redux reducers. * - * @param {Function} reducer The reducer to enhance - * @param {String} reducerKey The reducer key to persist + * @param {Function} reducer The reducer to enhance. + * @param {string} reducerKey The reducer key to persist. * * @returns {Function} Enhanced reducer. */ @@ -30,14 +30,14 @@ export function withRehydratation( reducer, reducerKey ) { } /** - * Loads the initial state and persist on changes + * Loads the initial state and persist on changes. * - * This should be executed after the reducer's registration + * This should be executed after the reducer's registration. * - * @param {Object} store Store to enhance - * @param {String} reducerKey The reducer key to persist (example: reducerKey.subReducerKey) - * @param {String} storageKey The storage key to use - * @param {Object} defaults Default values of the reducer key + * @param {Object} store Store to enhance. + * @param {string} reducerKey The reducer key to persist (example: reducerKey.subReducerKey). + * @param {string} storageKey The storage key to use. + * @param {Object} defaults Default values of the reducer key. */ export function loadAndPersist( store, reducerKey, storageKey, defaults = {} ) { // Load initially persisted value diff --git a/editor/store/reducer.js b/editor/store/reducer.js index d50531896b461..c3ad11076d10f 100644 --- a/editor/store/reducer.js +++ b/editor/store/reducer.js @@ -42,7 +42,7 @@ const MAX_RECENT_BLOCKS = 8; * Returns a post attribute value, flattening nested rendered content using its * raw value in place of its original object form. * - * @param {*} value Original value + * @param {*} value Original value. * * @returns {*} Raw value. */ @@ -64,8 +64,8 @@ export function getPostRawValue( value ) { * - blocksByUid: post content blocks keyed by UID * - blockOrder: list of block UIDs in order * - * @param {Object} state Current state - * @param {Object} action Dispatched action + * @param {Object} state Current state. + * @param {Object} action Dispatched action. * * @returns {Object} Updated state. */ @@ -311,8 +311,8 @@ export const editor = flow( [ * Reducer returning the last-known state of the current post, in the format * returned by the WP REST API. * - * @param {Object} state Current state - * @param {Object} action Dispatched action + * @param {Object} state Current state. + * @param {Object} action Dispatched action. * * @returns {Object} Updated state. */ @@ -341,10 +341,10 @@ export function currentPost( state = {}, action ) { /** * Reducer returning typing state. * - * @param {Boolean} state Current state - * @param {Object} action Dispatched action + * @param {boolean} state Current state. + * @param {Object} action Dispatched action. * - * @returns {Boolean} Updated state. + * @returns {boolean} Updated state. */ export function isTyping( state = false, action ) { switch ( action.type ) { @@ -361,8 +361,8 @@ export function isTyping( state = false, action ) { /** * Reducer returning the block selection's state. * - * @param {Object} state Current state - * @param {Object} action Dispatched action + * @param {Object} state Current state. + * @param {Object} action Dispatched action. * * @returns {Object} Updated state. */ @@ -449,8 +449,8 @@ export function blockSelection( state = { /** * Reducer returning hovered block state. * - * @param {Object} state Current state - * @param {Object} action Dispatched action + * @param {Object} state Current state. + * @param {Object} action Dispatched action. * * @returns {Object} Updated state. */ @@ -486,10 +486,10 @@ export function blocksMode( state = {}, action ) { } /** - * Reducer returning the block insertion point + * Reducer returning the block insertion point. * - * @param {Object} state Current state - * @param {Object} action Dispatched action + * @param {Object} state Current state. + * @param {Object} action Dispatched action. * * @returns {Object} Updated state. */ @@ -506,13 +506,13 @@ export function blockInsertionPoint( state = {}, action ) { } /** - * Reducer returning the user preferences: + * Reducer returning the user preferences. * - * @param {Object} state Current state - * @param {string} state.mode Current editor mode, either "visual" or "text". - * @param {Boolean} state.isSidebarOpened Whether the sidebar is opened or closed - * @param {Object} state.panels The state of the different sidebar panels - * @param {Object} action Dispatched action + * @param {Object} state Current state. + * @param {string} state.mode Current editor mode, either "visual" or "text". + * @param {boolean} state.isSidebarOpened Whether the sidebar is opened or closed. + * @param {Object} state.panels The state of the different sidebar panels. + * @param {Object} action Dispatched action. * * @returns {string} Updated state. */ @@ -593,11 +593,11 @@ export function panel( state = 'document', action ) { } /** - * Reducer returning current network request state (whether a request to the WP - * REST API is in progress, successful, or failed). + * Reducer returning current network request state (whether a request to + * the WP REST API is in progress, successful, or failed). * - * @param {Object} state Current state - * @param {Object} action Dispatched action + * @param {Object} state Current state. + * @param {Object} action Dispatched action. * * @returns {Object} Updated state. */ diff --git a/editor/store/selectors.js b/editor/store/selectors.js index 82d1b82d40e31..bf866587511a6 100644 --- a/editor/store/selectors.js +++ b/editor/store/selectors.js @@ -31,9 +31,9 @@ const MAX_FREQUENT_BLOCKS = 3; /** * Returns the current editing mode. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {String} Editing mode. + * @returns {string} Editing mode. */ export function getEditorMode( state ) { return getPreference( state, 'mode', 'visual' ); @@ -42,7 +42,7 @@ export function getEditorMode( state ) { /** * Returns the state of legacy meta boxes. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {Object} State of meta boxes. */ @@ -53,8 +53,8 @@ export function getMetaBoxes( state ) { /** * Returns the state of legacy meta boxes. * - * @param {Object} state Global application state - * @param {String} location Location of the meta box. + * @param {Object} state Global application state. + * @param {string} location Location of the meta box. * * @returns {Object} State of meta box at specified location. */ @@ -65,7 +65,7 @@ export function getMetaBox( state, location ) { /** * Returns a list of dirty meta box locations. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {Array} Array of locations for dirty meta boxes. */ @@ -86,27 +86,27 @@ export const getDirtyMetaBoxes = createSelector( * Checks whether the entire meta box state is dirty. So if a sidebar is dirty, * but a normal area is not dirty, this will overall return dirty. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Boolean} Whether state is dirty. True if dirty, false if not. + * @returns {boolean} Whether state is dirty. True if dirty, false if not. */ export const isMetaBoxStateDirty = ( state ) => getDirtyMetaBoxes( state ).length > 0; /** * Returns the current active panel for the sidebar. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {String} Active sidebar panel. + * @returns {string} Active sidebar panel. */ export function getActivePanel( state ) { return state.panel; } /** - * Returns the preferences (these preferences are persisted locally) + * Returns the preferences (these preferences are persisted locally). * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {Object} Preferences Object. */ @@ -116,9 +116,9 @@ export function getPreferences( state ) { /** * - * @param {Object} state Global application state - * @param {String} preferenceKey Preference Key - * @param {Mixed} defaultValue Default Value + * @param {Object} state Global application state. + * @param {string} preferenceKey Preference Key. + * @param {Mixed} defaultValue Default Value. * * @returns {Mixed} Preference Value. */ @@ -131,10 +131,10 @@ export function getPreference( state, preferenceKey, defaultValue ) { /** * Returns true if the sidebar is open, or false otherwise. * - * @param {Object} state Global application state - * @param {string} sidebar Sidebar name (leave undefined for the default sidebar) + * @param {Object} state Global application state. + * @param {string} sidebar Sidebar name (leave undefined for the default sidebar). * - * @returns {Boolean} Whether the given sidebar is open. + * @returns {boolean} Whether the given sidebar is open. */ export function isSidebarOpened( state, sidebar ) { const sidebars = getPreference( state, 'sidebars' ); @@ -146,11 +146,11 @@ export function isSidebarOpened( state, sidebar ) { } /** - * Returns true if there's any open sidebar (mobile, desktop or publish) + * Returns true if there's any open sidebar (mobile, desktop or publish). * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Boolean} Whether sidebar is open. + * @returns {boolean} Whether sidebar is open. */ export function hasOpenSidebar( state ) { const sidebars = getPreference( state, 'sidebars' ); @@ -162,10 +162,10 @@ export function hasOpenSidebar( state ) { /** * Returns true if the editor sidebar panel is open, or false otherwise. * - * @param {Object} state Global application state - * @param {STring} panel Sidebar panel name + * @param {Object} state Global application state. + * @param {string} panel Sidebar panel name. * - * @returns {Boolean} Whether sidebar is open. + * @returns {boolean} Whether sidebar is open. */ export function isEditorSidebarPanelOpened( state, panel ) { const panels = getPreference( state, 'panels' ); @@ -175,9 +175,9 @@ export function isEditorSidebarPanelOpened( state, panel ) { /** * Returns true if any past editor history snapshots exist, or false otherwise. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Boolean} Whether undo history exists. + * @returns {boolean} Whether undo history exists. */ export function hasEditorUndo( state ) { return state.editor.past.length > 0; @@ -187,9 +187,9 @@ export function hasEditorUndo( state ) { * Returns true if any future editor history snapshots exist, or false * otherwise. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Boolean} Whether redo history exists. + * @returns {boolean} Whether redo history exists. */ export function hasEditorRedo( state ) { return state.editor.future.length > 0; @@ -199,9 +199,9 @@ export function hasEditorRedo( state ) { * Returns true if the currently edited post is yet to be saved, or false if * the post has been saved. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Boolean} Whether the post is new. + * @returns {boolean} Whether the post is new. */ export function isEditedPostNew( state ) { return getCurrentPost( state ).status === 'auto-draft'; @@ -211,9 +211,9 @@ export function isEditedPostNew( state ) { * Returns true if there are unsaved values for the current edit session, or * false if the editing state matches the saved or new post. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Boolean} Whether unsaved values exist. + * @returns {boolean} Whether unsaved values exist. */ export function isEditedPostDirty( state ) { return state.editor.isDirty || isMetaBoxStateDirty( state ); @@ -223,20 +223,20 @@ export function isEditedPostDirty( state ) { * Returns true if there are no unsaved values for the current edit session and if * the currently edited post is new (and has never been saved before). * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Boolean} Whether new post and unsaved values exist. + * @returns {boolean} Whether new post and unsaved values exist. */ export function isCleanNewPost( state ) { return ! isEditedPostDirty( state ) && isEditedPostNew( state ); } /** - * Returns true if the current window size corresponds to mobile resolutions (<= medium breakpoint) + * Returns true if the current window size corresponds to mobile resolutions (<= medium breakpoint). * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Boolean} Whether current window size corresponds to + * @returns {boolean} Whether current window size corresponds to * mobile resolutions. */ export function isMobile( state ) { @@ -248,7 +248,7 @@ export function isMobile( state ) { * including unsaved edits. Returns an object containing relevant default post * values if the post has not yet been saved. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {Object} Post object. */ @@ -257,11 +257,11 @@ export function getCurrentPost( state ) { } /** - * Returns the post type of the post currently being edited + * Returns the post type of the post currently being edited. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {String} Post type. + * @returns {string} Post type. */ export function getCurrentPostType( state ) { return state.currentPost.type; @@ -271,7 +271,7 @@ export function getCurrentPostType( state ) { * Returns the ID of the post currently being edited, or null if the post has * not yet been saved. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {?Number} ID of current post. */ @@ -282,9 +282,9 @@ export function getCurrentPostId( state ) { /** * Returns the number of revisions of the post currently being edited. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Number} Number of revisions. + * @returns {number} Number of revisions. */ export function getCurrentPostRevisionsCount( state ) { return get( getCurrentPost( state ), 'revisions.count', 0 ); @@ -294,7 +294,7 @@ export function getCurrentPostRevisionsCount( state ) { * Returns the last revision ID of the post currently being edited, * or null if the post has no revisions. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {?Number} ID of the last revision. */ @@ -306,7 +306,7 @@ export function getCurrentPostLastRevisionId( state ) { * Returns any post values which have been changed in the editor but not yet * been saved. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {Object} Object of key value pairs comprising unsaved edits. */ @@ -319,8 +319,8 @@ export function getPostEdits( state ) { * edit if one exists, but falling back to the attribute for the last known * saved state of the post. * - * @param {Object} state Global application state - * @param {String} attributeName Post attribute name + * @param {Object} state Global application state. + * @param {string} attributeName Post attribute name. * * @returns {*} Post attribute value. */ @@ -335,9 +335,9 @@ export function getEditedPostAttribute( state, attributeName ) { * unsaved value if different than the saved post. The return value is one of * "private", "password", or "public". * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {String} Post visibility. + * @returns {string} Post visibility. */ export function getEditedPostVisibility( state ) { const status = getEditedPostAttribute( state, 'status' ); @@ -354,9 +354,9 @@ export function getEditedPostVisibility( state ) { /** * Return true if the current post has already been published. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Boolean} Whether the post has been published. + * @returns {boolean} Whether the post has been published. */ export function isCurrentPostPublished( state ) { const post = getCurrentPost( state ); @@ -366,11 +366,11 @@ export function isCurrentPostPublished( state ) { } /** - * Return true if the post being edited can be published + * Return true if the post being edited can be published. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Boolean} Whether the post can been published. + * @returns {boolean} Whether the post can been published. */ export function isEditedPostPublishable( state ) { const post = getCurrentPost( state ); @@ -381,9 +381,9 @@ export function isEditedPostPublishable( state ) { * Returns true if the post can be saved, or false otherwise. A post must * contain a title, an excerpt, or non-empty content to be valid for save. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Boolean} Whether the post can be saved. + * @returns {boolean} Whether the post can be saved. */ export function isEditedPostSaveable( state ) { return ( @@ -397,9 +397,9 @@ export function isEditedPostSaveable( state ) { * Return true if the post being edited is being scheduled. Preferring the * unsaved status values. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Boolean} Whether the post has been published. + * @returns {boolean} Whether the post has been published. */ export function isEditedPostBeingScheduled( state ) { const date = getEditedPostAttribute( state, 'date' ); @@ -413,9 +413,9 @@ export function isEditedPostBeingScheduled( state ) { * Returns the raw title of the post being edited, preferring the unsaved value * if different than the saved post. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {String} Raw post title. + * @returns {string} Raw post title. */ export function getEditedPostTitle( state ) { const editedTitle = getPostEdits( state ).title; @@ -432,7 +432,7 @@ export function getEditedPostTitle( state ) { /** * Gets the document title to be used. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {string} Document title. */ @@ -449,9 +449,9 @@ export function getDocumentTitle( state ) { * Returns the raw excerpt of the post being edited, preferring the unsaved * value if different than the saved post. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {String} Raw post excerpt. + * @returns {string} Raw post excerpt. */ export function getEditedPostExcerpt( state ) { return state.editor.present.edits.excerpt === undefined ? @@ -462,9 +462,9 @@ export function getEditedPostExcerpt( state ) { /** * Returns a URL to preview the post being edited. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {String} Preview URL. + * @returns {string} Preview URL. */ export function getEditedPostPreviewLink( state ) { const link = state.currentPost.link; @@ -481,8 +481,8 @@ export function getEditedPostPreviewLink( state ) { * state. This is not the block's registration settings, which must be * retrieved from the blocks module registration store. * - * @param {Object} state Global application state - * @param {String} uid Block unique ID + * @param {Object} state Global application state. + * @param {string} uid Block unique ID. * * @returns {Object} Parsed block object. */ @@ -536,7 +536,7 @@ function getPostMeta( state, key ) { * the order they appear in the post. * Note: It's important to memoize this selector to avoid return a new instance on each call * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {Object[]} Post blocks. */ @@ -553,9 +553,9 @@ export const getBlocks = createSelector( /** * Returns the number of blocks currently present in the post. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Number} Number of blocks in the post. + * @returns {number} Number of blocks in the post. */ export function getBlockCount( state ) { return getBlockUids( state ).length; @@ -564,9 +564,9 @@ export function getBlockCount( state ) { /** * Returns the number of blocks currently selected in the post. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Number} Number of blocks selected in the post. + * @returns {number} Number of blocks selected in the post. */ export function getSelectedBlockCount( state ) { const multiSelectedBlockCount = getMultiSelectedBlockUids( state ).length; @@ -581,7 +581,7 @@ export function getSelectedBlockCount( state ) { /** * Returns the currently selected block, or null if there is no selected block. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {?Object} Selected block. */ @@ -598,7 +598,7 @@ export function getSelectedBlock( state ) { * Returns the current multi-selection set of blocks unique IDs, or an empty * array if there is no multi-selection. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {Array} Multi-selected block unique IDs. */ @@ -630,7 +630,7 @@ export const getMultiSelectedBlockUids = createSelector( * Returns the current multi-selection set of blocks, or an empty array if * there is no multi-selection. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {Array} Multi-selected block objects. */ @@ -650,7 +650,7 @@ export const getMultiSelectedBlocks = createSelector( * Returns the unique ID of the first block in the multi-selection set, or null * if there is no multi-selection. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {?String} First unique block ID in the multi-selection set. */ @@ -662,7 +662,7 @@ export function getFirstMultiSelectedBlockUid( state ) { * Returns the unique ID of the last block in the multi-selection set, or null * if there is no multi-selection. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {?String} Last unique block ID in the multi-selection set. */ @@ -675,10 +675,10 @@ export function getLastMultiSelectedBlockUid( state ) { * specified unique ID is the first block of the multi-selection set, or false * otherwise. * - * @param {Object} state Global application state - * @param {String} uid Block unique ID + * @param {Object} state Global application state. + * @param {string} uid Block unique ID. * - * @returns {Boolean} Whether block is first in mult-selection. + * @returns {boolean} Whether block is first in mult-selection. */ export function isFirstMultiSelectedBlock( state, uid ) { return getFirstMultiSelectedBlockUid( state ) === uid; @@ -688,10 +688,10 @@ export function isFirstMultiSelectedBlock( state, uid ) { * Returns true if the unique ID occurs within the block multi-selection, or * false otherwise. * - * @param {Object} state Global application state - * @param {String} uid Block unique ID + * @param {Object} state Global application state. + * @param {string} uid Block unique ID. * - * @returns {Boolean} Whether block is in multi-selection set. + * @returns {boolean} Whether block is in multi-selection set. */ export function isBlockMultiSelected( state, uid ) { return getMultiSelectedBlockUids( state ).indexOf( uid ) !== -1; @@ -704,7 +704,7 @@ export function isBlockMultiSelected( state, uid ) { * N.b.: This is not necessarily the first uid in the selection. See * getFirstMultiSelectedBlockUid(). * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {?String} Unique ID of block beginning multi-selection. */ @@ -723,7 +723,7 @@ export function getMultiSelectedBlocksStartUid( state ) { * N.b.: This is not necessarily the last uid in the selection. See * getLastMultiSelectedBlockUid(). * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {?String} Unique ID of block ending multi-selection. */ @@ -739,7 +739,7 @@ export function getMultiSelectedBlocksEndUid( state ) { * Returns an array containing all block unique IDs of the post being edited, * in the order they appear in the post. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {Array} Ordered unique IDs of post blocks. */ @@ -748,13 +748,13 @@ export function getBlockUids( state ) { } /** - * Returns the index at which the block corresponding to the specified unique - * ID occurs within the post block order, or `-1` if the block does not exist. + * Returns the index at which the block corresponding to the specified unique ID + * occurs within the post block order, or `-1` if the block does not exist. * - * @param {Object} state Global application state - * @param {String} uid Block unique ID + * @param {Object} state Global application state. + * @param {string} uid Block unique ID. * - * @returns {Number} Index at which block exists in order. + * @returns {number} Index at which block exists in order. */ export function getBlockIndex( state, uid ) { return state.editor.present.blockOrder.indexOf( uid ); @@ -764,10 +764,10 @@ export function getBlockIndex( state, uid ) { * Returns true if the block corresponding to the specified unique ID is the * first block of the post, or false otherwise. * - * @param {Object} state Global application state - * @param {String} uid Block unique ID + * @param {Object} state Global application state. + * @param {string} uid Block unique ID. * - * @returns {Boolean} Whether block is first in post. + * @returns {boolean} Whether block is first in post. */ export function isFirstBlock( state, uid ) { return first( state.editor.present.blockOrder ) === uid; @@ -777,10 +777,10 @@ export function isFirstBlock( state, uid ) { * Returns true if the block corresponding to the specified unique ID is the * last block of the post, or false otherwise. * - * @param {Object} state Global application state - * @param {String} uid Block unique ID + * @param {Object} state Global application state. + * @param {string} uid Block unique ID. * - * @returns {Boolean} Whether block is last in post. + * @returns {boolean} Whether block is last in post. */ export function isLastBlock( state, uid ) { return last( state.editor.present.blockOrder ) === uid; @@ -790,8 +790,8 @@ export function isLastBlock( state, uid ) { * Returns the block object occurring before the one corresponding to the * specified unique ID. * - * @param {Object} state Global application state - * @param {String} uid Block unique ID + * @param {Object} state Global application state. + * @param {string} uid Block unique ID. * * @returns {Object} Block occurring before specified unique ID. */ @@ -804,8 +804,8 @@ export function getPreviousBlock( state, uid ) { * Returns the block object occurring after the one corresponding to the * specified unique ID. * - * @param {Object} state Global application state - * @param {String} uid Block unique ID + * @param {Object} state Global application state. + * @param {string} uid Block unique ID. * * @returns {Object} Block occurring after specified unique ID. */ @@ -818,10 +818,10 @@ export function getNextBlock( state, uid ) { * Returns true if the block corresponding to the specified unique ID is * currently selected and no multi-selection exists, or false otherwise. * - * @param {Object} state Global application state - * @param {String} uid Block unique ID + * @param {Object} state Global application state. + * @param {string} uid Block unique ID. * - * @returns {Boolean} Whether block is selected and multi-selection exists. + * @returns {boolean} Whether block is selected and multi-selection exists. */ export function isBlockSelected( state, uid ) { const { start, end } = state.blockSelection; @@ -839,10 +839,10 @@ export function isBlockSelected( state, uid ) { * refers to the block sequence in the document, _not_ the sequence of * multi-selection, which is why `state.blockSelection.end` isn't used. * - * @param {Object} state Global application state - * @param {String} uid Block unique ID + * @param {Object} state Global application state. + * @param {string} uid Block unique ID. * - * @returns {Boolean} Whether block is selected and not the last in + * @returns {boolean} Whether block is selected and not the last in * the selection. */ export function isBlockWithinSelection( state, uid ) { @@ -859,10 +859,10 @@ export function isBlockWithinSelection( state, uid ) { * Returns true if the cursor is hovering the block corresponding to the * specified unique ID, or false otherwise. * - * @param {Object} state Global application state - * @param {String} uid Block unique ID + * @param {Object} state Global application state. + * @param {string} uid Block unique ID. * - * @returns {Boolean} Whether block is hovered. + * @returns {boolean} Whether block is hovered. */ export function isBlockHovered( state, uid ) { return state.hoveredBlock === uid; @@ -873,8 +873,8 @@ export function isBlockHovered( state, uid ) { * or null if the block is not selected. It is left to a block's implementation * to manage the content of this object, defaulting to an empty object. * - * @param {Object} state Global application state - * @param {String} uid Block unique ID + * @param {Object} state Global application state. + * @param {string} uid Block unique ID. * * @returns {Object} Block focus state. */ @@ -890,9 +890,9 @@ export function getBlockFocus( state, uid ) { /** * Whether in the process of multi-selecting or not. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Boolean} True if multi-selecting, false if not. + * @returns {boolean} True if multi-selecting, false if not. */ export function isMultiSelecting( state ) { return state.blockSelection.isMultiSelecting; @@ -901,19 +901,19 @@ export function isMultiSelecting( state ) { /** * Whether is selection disable or not. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Boolean} True if multi is disable, false if not. + * @returns {boolean} True if multi is disable, false if not. */ export function isSelectionEnabled( state ) { return state.blockSelection.isEnabled; } /** - * Returns thee block's editing mode + * Returns thee block's editing mode. * - * @param {Object} state Global application state - * @param {String} uid Block unique ID + * @param {Object} state Global application state. + * @param {string} uid Block unique ID. * * @returns {Object} Block editing mode. */ @@ -924,9 +924,9 @@ export function getBlockMode( state, uid ) { /** * Returns true if the user is typing, or false otherwise. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Boolean} Whether user is typing. + * @returns {boolean} Whether user is typing. */ export function isTyping( state ) { return state.isTyping; @@ -934,9 +934,9 @@ export function isTyping( state ) { /** * Returns the insertion point, the index at which the new inserted block would - * be placed. Defaults to the last position + * be placed. Defaults to the last position. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {?String} Unique ID after which insertion will occur. */ @@ -967,7 +967,7 @@ export function getBlockInsertionPoint( state ) { * Returns the position at which the block inserter will insert a new adjacent * sibling block, or null if the inserter is not actively visible. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {?Number} Whether the inserter is currently visible. */ @@ -981,9 +981,9 @@ export function getBlockSiblingInserterPosition( state ) { } /** - * Returns true if we should show the block insertion point + * Returns true if we should show the block insertion point. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {?Boolean} Whether the insertion point is visible or not. */ @@ -994,9 +994,9 @@ export function isBlockInsertionPointVisible( state ) { /** * Returns true if the post is currently being saved, or false otherwise. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Boolean} Whether post is being saved. + * @returns {boolean} Whether post is being saved. */ export function isSavingPost( state ) { return state.saving.requesting; @@ -1006,9 +1006,9 @@ export function isSavingPost( state ) { * Returns true if a previous post save was attempted successfully, or false * otherwise. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Boolean} Whether the post was saved successfully. + * @returns {boolean} Whether the post was saved successfully. */ export function didPostSaveRequestSucceed( state ) { return state.saving.successful; @@ -1018,9 +1018,9 @@ export function didPostSaveRequestSucceed( state ) { * Returns true if a previous post save was attempted but failed, or false * otherwise. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Boolean} Whether the post save failed. + * @returns {boolean} Whether the post save failed. */ export function didPostSaveRequestFail( state ) { return !! state.saving.error; @@ -1031,7 +1031,7 @@ export function didPostSaveRequestFail( state ) { * is a single block within the post and it is of a type known to match a * default post format. Returns null if the format cannot be determined. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {?String} Suggested post format. */ @@ -1079,9 +1079,9 @@ export function getSuggestedPostFormat( state ) { * Returns the content of the post being edited, preferring raw string edit * before falling back to serialization of block state. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {String} Post content. + * @returns {string} Post content. */ export const getEditedPostContent = createSelector( ( state ) => { @@ -1100,9 +1100,9 @@ export const getEditedPostContent = createSelector( ); /** - * Returns the user notices array + * Returns the user notices array. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {Array} List of notices. */ @@ -1113,7 +1113,7 @@ export function getNotices( state ) { /** * An item that appears in the inserter. Inserting this item will create a new * block. Inserter items encapsulate both regular blocks and reusable blocks. - * + * * @typedef {Object} Editor.InserterItem * @property {string} id Unique identifier for the item. * @property {string} name The type of block to create. @@ -1127,11 +1127,12 @@ export function getNotices( state ) { /** * Given a regular block type, constructs an item that appears in the inserter. - * - * @param {Object} state Global application state. - * @param {string[]|boolean} enabledBlockTypes Enabled block types, or true/false to enable/disable all types. - * @param {Object} blockType Block type, likely from getBlockType(). - * @returns {Editor.InserterItem} Item that appears in inserter. + * + * @param {Object} state Global application state. + * @param {string[]|boolean} enabledBlockTypes Enabled block types, or true/false to enable/disable all types. + * @param {Object} blockType Block type, likely from getBlockType(). + * + * @returns {Editor.InserterItem} Item that appears in inserter. */ function buildInserterItemFromBlockType( state, enabledBlockTypes, blockType ) { if ( ! enabledBlockTypes || ! blockType ) { @@ -1161,10 +1162,11 @@ function buildInserterItemFromBlockType( state, enabledBlockTypes, blockType ) { /** * Given a reusable block, constructs an item that appears in the inserter. - * - * @param {string[]|boolean} enabledBlockTypes Enabled block types, or true/false to enable/disable all types. - * @param {Object} reusableBlock Reusable block, likely from getReusableBlock(). - * @returns {Editor.InserterItem} Item that appears in inserter. + * + * @param {string[]|boolean} enabledBlockTypes Enabled block types, or true/false to enable/disable all types. + * @param {Object} reusableBlock Reusable block, likely from getReusableBlock(). + * + * @returns {Editor.InserterItem} Item that appears in inserter. */ function buildInserterItemFromReusableBlock( enabledBlockTypes, reusableBlock ) { if ( ! enabledBlockTypes || ! reusableBlock ) { @@ -1196,10 +1198,11 @@ function buildInserterItemFromReusableBlock( enabledBlockTypes, reusableBlock ) /** * Determines the items that appear in the the inserter. Includes both static * items (e.g. a regular block type) and dynamic items (e.g. a reusable block). - * - * @param {Object} state Global application state. - * @param {string[]|boolean} enabledBlockTypes Enabled block types, or true/false to enable/disable all types. - * @returns {Editor.InserterItem[]} Items that appear in inserter. + * + * @param {Object} state Global application state. + * @param {string[]|boolean} enabledBlockTypes Enabled block types, or true/false to enable/disable all types. + * + * @returns {Editor.InserterItem[]} Items that appear in inserter. */ export function getInserterItems( state, enabledBlockTypes = true ) { if ( ! enabledBlockTypes ) { @@ -1220,10 +1223,11 @@ export function getInserterItems( state, enabledBlockTypes = true ) { /** * Determines the items that appear in the 'Recent' tab of the inserter. - * - * @param {Object} state Global application state. - * @param {string[]|boolean} enabledBlockTypes Enabled block types, or true/false to enable/disable all types. - * @returns {Editor.InserterItem[]} Items that appear in the 'Recent' tab. + * + * @param {Object} state Global application state. + * @param {string[]|boolean} enabledBlockTypes Enabled block types, or true/false to enable/disable all types. + * + * @returns {Editor.InserterItem[]} Items that appear in the 'Recent' tab. */ export function getRecentInserterItems( state, enabledBlockTypes = true ) { if ( ! enabledBlockTypes ) { @@ -1244,7 +1248,7 @@ export function getRecentInserterItems( state, enabledBlockTypes = true ) { * Memoized so we're not generating block lists every time we render the list * in the inserter. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {Array} List of block type settings. */ @@ -1264,21 +1268,21 @@ export const getMostFrequentlyUsedBlocks = createSelector( /** * Returns whether the toolbar should be fixed or not. * - * @param {Object} state Global application state. + * @param {Object} state Global application state. * - * @returns {Boolean} True if toolbar is fixed. + * @returns {boolean} True if toolbar is fixed. */ export function hasFixedToolbar( state ) { return ! isMobile( state ) && isFeatureActive( state, 'fixedToolbar' ); } /** - * Returns whether the given feature is enabled or not + * Returns whether the given feature is enabled or not. * - * @param {Object} state Global application state - * @param {String} feature Feature slug + * @param {Object} state Global application state. + * @param {string} feature Feature slug. * - * @returns {Booleean} Is active. + * @returns {booleean} Is active. */ export function isFeatureActive( state, feature ) { return !! state.preferences.features[ feature ]; @@ -1287,8 +1291,8 @@ export function isFeatureActive( state, feature ) { /** * Returns the reusable block with the given ID. * - * @param {Object} state Global application state - * @param {String} ref The reusable block's ID + * @param {Object} state Global application state. + * @param {string} ref The reusable block's ID. * * @returns {Object} The reusable block, or null if none exists. */ @@ -1299,10 +1303,10 @@ export function getReusableBlock( state, ref ) { /** * Returns whether or not the reusable block with the given ID is being saved. * - * @param {*} state Global application state - * @param {*} ref The reusable block's ID + * @param {*} state Global application state. + * @param {*} ref The reusable block's ID. * - * @returns {Boolean} Whether or not the reusable block is being saved. + * @returns {boolean} Whether or not the reusable block is being saved. */ export function isSavingReusableBlock( state, ref ) { return state.reusableBlocks.isSaving[ ref ] || false; @@ -1311,7 +1315,7 @@ export function isSavingReusableBlock( state, ref ) { /** * Returns an array of all reusable blocks. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * * @returns {Array} An array of all reusable blocks. */ @@ -1323,8 +1327,8 @@ export function getReusableBlocks( state ) { * Returns state object prior to a specified optimist transaction ID, or `null` * if the transaction corresponding to the given ID cannot be found. * - * @param {Object} state Current global application state - * @param {Object} transactionId Optimist transaction ID + * @param {Object} state Current global application state. + * @param {Object} transactionId Optimist transaction ID. * * @returns {Object} Global application state prior to transaction. */ @@ -1338,11 +1342,11 @@ export function getStateBeforeOptimisticTransaction( state, transactionId ) { } /** - * Returns true if the post is being published, or false otherwise + * Returns true if the post is being published, or false otherwise. * - * @param {Object} state Global application state + * @param {Object} state Global application state. * - * @returns {Boolean} Whether post is being published. + * @returns {boolean} Whether post is being published. */ export function isPublishingPost( state ) { if ( ! isSavingPost( state ) ) { diff --git a/editor/utils/dom.js b/editor/utils/dom.js index 04ed1ed96f734..eed1b7028804b 100644 --- a/editor/utils/dom.js +++ b/editor/utils/dom.js @@ -12,11 +12,11 @@ const { TEXT_NODE } = window.Node; /** * Check whether the caret is horizontally at the edge of the container. * - * @param {Element} container Focusable element. - * @param {Boolean} isReverse Set to true to check left, false for right. - * @param {Boolean} collapseRanges Whether or not to collapse the selection range before the check + * @param {Element} container Focusable element. + * @param {boolean} isReverse Set to true to check left, false for right. + * @param {boolean} collapseRanges Whether or not to collapse the selection range before the check. * - * @returns {Boolean} True if at the horizontal edge, false if not. + * @returns {boolean} True if at the horizontal edge, false if not. */ export function isHorizontalEdge( container, isReverse, collapseRanges = false ) { if ( includes( [ 'INPUT', 'TEXTAREA' ], container.tagName ) ) { @@ -78,11 +78,11 @@ export function isHorizontalEdge( container, isReverse, collapseRanges = false ) /** * Check whether the caret is vertically at the edge of the container. * - * @param {Element} container Focusable element. - * @param {Boolean} isReverse Set to true to check top, false for bottom. - * @param {Boolean} collapseRanges Whether or not to collapse the selection range before the check + * @param {Element} container Focusable element. + * @param {boolean} isReverse Set to true to check top, false for bottom. + * @param {boolean} collapseRanges Whether or not to collapse the selection range before the check. * - * @returns {Boolean} True if at the edge, false if not. + * @returns {boolean} True if at the edge, false if not. */ export function isVerticalEdge( container, isReverse, collapseRanges = false ) { if ( includes( [ 'INPUT', 'TEXTAREA' ], container.tagName ) ) { @@ -158,7 +158,7 @@ export function computeCaretRect( container ) { * Places the caret at start or end of a given element. * * @param {Element} container Focusable element. - * @param {Boolean} isReverse True for end, false for start. + * @param {boolean} isReverse True for end, false for start. */ export function placeCaretAtHorizontalEdge( container, isReverse ) { if ( ! container ) { @@ -200,9 +200,9 @@ export function placeCaretAtHorizontalEdge( container, isReverse ) { * * @see https://developer.mozilla.org/en-US/docs/Web/API/Document/caretRangeFromPoint * - * @param {Document} doc The document of the range. - * @param {Float} x Horizontal position within the current viewport. - * @param {Float} y Vertical position within the current viewport. + * @param {Document} doc The document of the range. + * @param {Float} x Horizontal position within the current viewport. + * @param {Float} y Vertical position within the current viewport. * * @returns {?Range} The best range for the given point. */ @@ -229,10 +229,10 @@ function caretRangeFromPoint( doc, x, y ) { * Gives the container a temporary high z-index (above any UI). * This is preferred over getting the UI nodes and set styles there. * - * @param {Document} doc The document of the range. - * @param {Float} x Horizontal position within the current viewport. - * @param {Float} y Vertical position within the current viewport. - * @param {Element} container Container in which the range is expected to be found. + * @param {Document} doc The document of the range. + * @param {Float} x Horizontal position within the current viewport. + * @param {Float} y Vertical position within the current viewport. + * @param {Element} container Container in which the range is expected to be found. * * @returns {?Range} The best range for the given point. */ @@ -250,9 +250,9 @@ function hiddenCaretRangeFromPoint( doc, x, y, container ) { * Places the caret at the top or bottom of a given element. * * @param {Element} container Focusable element. - * @param {Boolean} isReverse True for bottom, false for top. + * @param {boolean} isReverse True for bottom, false for top. * @param {DOMRect} [rect] The rectangle to position the caret with. - * @param {Boolean} [mayUseScroll=true] True to allow scrolling, false to disallow. + * @param {boolean} [mayUseScroll=true] True to allow scrolling, false to disallow. */ export function placeCaretAtVerticalEdge( container, isReverse, rect, mayUseScroll = true ) { if ( ! container ) { @@ -313,9 +313,9 @@ export function placeCaretAtVerticalEdge( container, isReverse, rect, mayUseScro /** * Check whether the given node in an input field. * - * @param {HTMLElement} element The HTML element. + * @param {HTMLElement} element The HTML element. * - * @returns {Boolean} True if the element is an input field, false if not. + * @returns {boolean} True if the element is an input field, false if not. */ export function isInputField( { nodeName, contentEditable } ) { return ( @@ -329,7 +329,7 @@ export function isInputField( { nodeName, contentEditable } ) { * Check wether the current document has a selection. * This checks both for focus in an input field and general text selection. * - * @returns {Boolean} True if there is selection, false if not. + * @returns {boolean} True if there is selection, false if not. */ export function documentHasSelection() { if ( isInputField( document.activeElement ) ) { diff --git a/editor/utils/mobile/index.js b/editor/utils/mobile/index.js index 697d73599210a..ab1201c478587 100644 --- a/editor/utils/mobile/index.js +++ b/editor/utils/mobile/index.js @@ -7,9 +7,9 @@ import { toggleSidebar } from '../../store/actions'; /** * Disables isSidebarOpened on rehydrate payload if the user is on a mobile screen size. * - * @param {Object} payload rehydrate payload + * @param {Object} payload Rehydrate payload. * - * @returns {Object} rehydrate payload with isSidebarOpened disabled if on mobile. + * @returns {Object} Rehydrate payload with isSidebarOpened disabled if on mobile. */ export const disableIsSidebarOpenedOnMobile = ( payload ) => ( payload.isSidebarOpenedMobile ? { ...payload, isSidebarOpenedMobile: false } : payload diff --git a/editor/utils/url.js b/editor/utils/url.js index 735d0bef6c612..007cb4fce559c 100644 --- a/editor/utils/url.js +++ b/editor/utils/url.js @@ -4,34 +4,34 @@ import { addQueryArgs } from '@wordpress/url'; /** - * Returns the Post's Edit URL + * Returns the Post's Edit URL. * - * @param {Number} postId Post ID + * @param {number} postId Post ID. * - * @returns {String} Post edit URL. + * @returns {string} Post edit URL. */ export function getPostEditUrl( postId ) { return getWPAdminURL( 'post.php', { post: postId, action: 'edit' } ); } /** - * Returns the url of a WPAdmin Page + * Returns the URL of a WPAdmin Page. * - * @param {String} page page to navigate to - * @param {Object} query Query Args + * @param {string} page Page to navigate to. + * @param {Object} query Query Args. * - * @returns {String} WPAdmin URL. + * @returns {string} WPAdmin URL. */ export function getWPAdminURL( page, query ) { return addQueryArgs( page, query ); } /** - * Returns a url for display + * Returns a URL for display. * - * @param {String} url Original url + * @param {string} url Original URL. * - * @returns {String} Displayed URL. + * @returns {string} Displayed URL. */ export function filterURLForDisplay( url ) { // remove protocol and www prefixes diff --git a/editor/utils/with-change-detection/index.js b/editor/utils/with-change-detection/index.js index 557b11fa55808..27063d41b9e86 100644 --- a/editor/utils/with-change-detection/index.js +++ b/editor/utils/with-change-detection/index.js @@ -8,9 +8,9 @@ import { includes } from 'lodash'; * returned reducer will include a new `isDirty` property on the object * reflecting whether the original reference of the reducer has changed. * - * @param {Function} reducer Original reducer - * @param {?Object} options Optional options - * @param {?Array} options.resetTypes Action types upon which to reset dirty + * @param {Function} reducer Original reducer. + * @param {?Object} options Optional . + * @param {?Array} options.resetTypes Action types upon which to reset dirty. * * @returns {Function} Enhanced reducer. */ diff --git a/editor/utils/with-history/index.js b/editor/utils/with-history/index.js index a01d9b3953f35..2335bbc22ee20 100644 --- a/editor/utils/with-history/index.js +++ b/editor/utils/with-history/index.js @@ -7,9 +7,9 @@ import { includes } from 'lodash'; * Reducer enhancer which transforms the result of the original reducer into an * object tracking its own history (past, present, future). * - * @param {Function} reducer Original reducer - * @param {?Object} options Optional options - * @param {?Array} options.resetTypes Action types upon which to clear past + * @param {Function} reducer Original reducer. + * @param {?Object} options Optional options. + * @param {?Array} options.resetTypes Action types upon which to clear past. * * @returns {Function} Enhanced reducer. */ diff --git a/element/index.js b/element/index.js index 33968682dd3e9..9f40e5ab22588 100644 --- a/element/index.js +++ b/element/index.js @@ -10,11 +10,11 @@ import { camelCase, flowRight, isString, upperFirst } from 'lodash'; * Returns a new element of given type. Type can be either a string tag name or * another function which itself returns an element. * - * @param {?(string|Function)} type Tag name or element creator - * @param {Object} props Element properties, either attribute + * @param {?(string|Function)} type Tag name or element creator + * @param {Object} props Element properties, either attribute * set to apply to DOM node or values to * pass through to element creator - * @param {...WPElement} children Descendant elements + * @param {...WPElement} children Descendant elements * * @returns {WPElement} Element. */ @@ -43,8 +43,8 @@ export { Component }; /** * Creates a copy of an element with extended props. * - * @param {WPElement} element Element - * @param {?Object} props Props to apply to cloned element + * @param {WPElement} element Element + * @param {?Object} props Props to apply to cloned element * * @returns {WPElement} Cloned element. */ @@ -76,18 +76,18 @@ export { Fragment }; export { createPortal }; /** - * Renders a given element into a string + * Renders a given element into a string. * - * @param {WPElement} element Element to render + * @param {WPElement} element Element to render * * @returns {String} HTML. */ export { renderToStaticMarkup as renderToString }; /** - * Concatenate two or more React children objects + * Concatenate two or more React children objects. * - * @param {...?Object} childrenArguments Array of children arguments (array of arrays/strings/objects) to concatenate + * @param {...?Object} childrenArguments Array of children arguments (array of arrays/strings/objects) to concatenate. * * @returns {Array} The concatenated value. */ @@ -108,10 +108,10 @@ export function concatChildren( ...childrenArguments ) { } /** - * Switches the nodeName of all the elements in the children object + * Switches the nodeName of all the elements in the children object. * - * @param {?Object} children Children object - * @param {String} nodeName Node name + * @param {?Object} children Children object. + * @param {string} nodeName Node name. * * @returns {?Object} The updated children object. */ @@ -139,10 +139,10 @@ export { flowRight as compose }; * Returns a wrapped version of a React component's display name. * Higher-order components use getWrapperDisplayName(). * - * @param {Function|Component} BaseComponent used to detect the existing display name. - * @param {String} wrapperName Wrapper name to prepend to the display name. + * @param {Function|Component} BaseComponent Used to detect the existing display name. + * @param {string} wrapperName Wrapper name to prepend to the display name. * - * @returns {String} Wrapped display name. + * @returns {string} Wrapped display name. */ export function getWrapperDisplayName( BaseComponent, wrapperName ) { const { displayName = BaseComponent.name || 'Component' } = BaseComponent; diff --git a/i18n/babel-plugin.js b/i18n/babel-plugin.js index 7d814f1ca65d0..670068fc21b14 100644 --- a/i18n/babel-plugin.js +++ b/i18n/babel-plugin.js @@ -86,9 +86,9 @@ const REGEXP_TRANSLATOR_COMMENT = /^\s*translators:\s*([\s\S]+)/im; * Given an argument node (or recursed node), attempts to return a string * represenation of that node's value. * - * @param {Object} node AST node + * @param {Object} node AST node. * - * @returns {String} String value. + * @returns {string} String value. */ function getNodeAsString( node ) { switch ( node.type ) { @@ -109,9 +109,9 @@ function getNodeAsString( node ) { /** * Returns translator comment for a given AST traversal path if one exists. * - * @param {Object} path Traversal path - * @param {Number} _originalNodeLine Private: In recursion, line number of - * the original node passed + * @param {Object} path Traversal path. + * @param {number} _originalNodeLine Private: In recursion, line number of + * the original node passed. * * @returns {?string} Translator comment. */ @@ -160,9 +160,9 @@ function getTranslatorComment( path, _originalNodeLine ) { * Returns true if the specified key of a function is valid for assignment in * the translation object. * - * @param {string} key Key to test + * @param {string} key Key to test. * - * @returns {Boolean} Whether key is valid for assignment. + * @returns {boolean} Whether key is valid for assignment. */ function isValidTranslationKey( key ) { return -1 !== VALID_TRANSLATION_KEYS.indexOf( key ); @@ -172,10 +172,10 @@ function isValidTranslationKey( key ) { * Given two translation objects, returns true if valid translation keys match, * or false otherwise. * - * @param {Object} a First translation object - * @param {Object} b Second translation object + * @param {Object} a First translation object. + * @param {Object} b Second translation object. * - * @returns {Boolean} Whether valid translation keys match. + * @returns {boolean} Whether valid translation keys match. */ function isSameTranslation( a, b ) { return isEqual( diff --git a/i18n/index.js b/i18n/index.js index c58abb308caf2..cb08e164dda1d 100644 --- a/i18n/index.js +++ b/i18n/index.js @@ -10,7 +10,7 @@ let i18n; * * @see http://messageformat.github.io/Jed/ * - * @param {Object} data Locale data configuration + * @param {Object} data Locale data configuration. */ export function setLocaleData( data ) { i18n = new Jed( data ); @@ -35,7 +35,7 @@ export function getI18n() { * * @see https://developer.wordpress.org/reference/functions/__/ * - * @param {string} text Text to translate + * @param {string} text Text to translate. * * @returns {string} Translated text. */ @@ -48,8 +48,8 @@ export function __( text ) { * * @see https://developer.wordpress.org/reference/functions/_x/ * - * @param {string} text Text to translate - * @param {string} context Context information for the translators + * @param {string} text Text to translate. + * @param {string} context Context information for the translators. * * @returns {string} Translated context string without pipe. */ @@ -63,10 +63,10 @@ export function _x( text, context ) { * * @see https://developer.wordpress.org/reference/functions/_n/ * - * @param {string} single The text to be used if the number is singular - * @param {string} plural The text to be used if the number is plural - * @param {Number} number The number to compare against to use either the - * singular or plural form + * @param {string} single The text to be used if the number is singular. + * @param {string} plural The text to be used if the number is plural. + * @param {number} number The number to compare against to use either the + * singular or plural form. * * @returns {string} The translated singular or plural form. */ @@ -80,11 +80,11 @@ export function _n( single, plural, number ) { * * @see https://developer.wordpress.org/reference/functions/_nx/ * - * @param {string} single The text to be used if the number is singular - * @param {string} plural The text to be used if the number is plural - * @param {Number} number The number to compare against to use either the - * singular or plural form - * @param {string} context Context information for the translators + * @param {string} single The text to be used if the number is singular. + * @param {string} plural The text to be used if the number is plural. + * @param {number} number The number to compare against to use either the + * singular or plural form. + * @param {string} context Context information for the translators. * * @returns {string} The translated singular or plural form. */ diff --git a/utils/focus/focusable.js b/utils/focus/focusable.js index 924f3f0c2003d..28d8d93a20378 100644 --- a/utils/focus/focusable.js +++ b/utils/focus/focusable.js @@ -40,9 +40,9 @@ const SELECTOR = [ * Returns true if the specified element is visible (i.e. neither display: none * nor visibility: hidden). * - * @param {Element} element DOM element to test + * @param {Element} element DOM element to test. * - * @returns {Boolean} Whether element is visible. + * @returns {boolean} Whether element is visible. */ function isVisible( element ) { return ( @@ -57,9 +57,9 @@ function isVisible( element ) { * false otherwise. Area is only focusable if within a map where a named map * referenced by an image somewhere in the document. * - * @param {Element} element DOM area element to test + * @param {Element} element DOM area element to test. * - * @returns {Boolean} Whether area element is valid for focus. + * @returns {boolean} Whether area element is valid for focus. */ function isValidFocusableArea( element ) { const map = element.closest( 'map[name]' ); @@ -74,7 +74,7 @@ function isValidFocusableArea( element ) { /** * Returns all focusable elements within a given context. * - * @param {Element} context Element in which to search + * @param {Element} context Element in which to search. * * @returns {Element[]} Focusable elements. */ diff --git a/utils/focus/tabbable.js b/utils/focus/tabbable.js index be18332b2830a..9faa395eb5ebc 100644 --- a/utils/focus/tabbable.js +++ b/utils/focus/tabbable.js @@ -11,7 +11,7 @@ import { find as findFocusable } from './focusable'; * * @see https://bugzilla.mozilla.org/show_bug.cgi?id=1190261 * - * @param {Element} element Element from which to retrieve + * @param {Element} element Element from which to retrieve. * * @returns {?Number} Tab index of element (default 0). */ @@ -23,9 +23,9 @@ function getTabIndex( element ) { /** * Returns true if the specified element is tabbable, or false otherwise. * - * @param {Element} element Element to test + * @param {Element} element Element to test. * - * @returns {Boolean} Whether element is tabbable. + * @returns {boolean} Whether element is tabbable. */ function isTabbableIndex( element ) { return getTabIndex( element ) !== -1; @@ -37,8 +37,8 @@ function isTabbableIndex( element ) { * sort where equal tabIndex should be left in order of their occurrence in the * document. * - * @param {Element} element Element - * @param {Number} index Array index of element + * @param {Element} element Element. + * @param {number} index Array index of element. * * @returns {Object} Mapped object with element, index. */ @@ -50,7 +50,7 @@ function mapElementToObjectTabbable( element, index ) { * An array map callback, returning an element of the given mapped object's * element value. * - * @param {Object} object Mapped object with index + * @param {Object} object Mapped object with index. * * @returns {Element} Mapped object element. */ @@ -63,10 +63,10 @@ function mapObjectTabbableToElement( object ) { * * @see mapElementToObjectTabbable * - * @param {Object} a First object to compare - * @param {Object} b Second object to compare + * @param {Object} a First object to compare. + * @param {Object} b Second object to compare. * - * @returns {Number} Comparator result. + * @returns {number} Comparator result. */ function compareObjectTabbables( a, b ) { const aTabIndex = getTabIndex( a.element ); diff --git a/utils/focus/test/utils/create-element.js b/utils/focus/test/utils/create-element.js index f7f2ef5ae8c58..289565374b1f9 100644 --- a/utils/focus/test/utils/create-element.js +++ b/utils/focus/test/utils/create-element.js @@ -2,7 +2,7 @@ * Given an element type, returns an HTMLElement with an emulated layout, * since JSDOM does have its own internal layout engine. * - * @param {String} type Element type + * @param {string} type Element type. * * @returns {HTMLElement} Layout-emulated element. */ diff --git a/utils/mediaupload.js b/utils/mediaupload.js index 21223c5ee32f0..fbf85adaf24f9 100644 --- a/utils/mediaupload.js +++ b/utils/mediaupload.js @@ -4,13 +4,13 @@ import { compact } from 'lodash'; /** - * Media Upload is used by image and gallery blocks to handle uploading an image + * Media Upload is used by image and gallery blocks to handle uploading an image. * when a file upload button is activated. * - * TODO: future enhancement to add an upload indicator + * TODO: future enhancement to add an upload indicator. * - * @param {Array} filesList List of files. - * @param {Function} onImagesChange Function to be called each time a file or a temporary representation of the file is available. + * @param {Array} filesList List of files. + * @param {Function} onImagesChange Function to be called each time a file or a temporary representation of the file is available. */ export function mediaUpload( filesList, onImagesChange ) { // Cast filesList to array @@ -46,7 +46,7 @@ export function mediaUpload( filesList, onImagesChange ) { } /** - * @param {File} file Media File to Save + * @param {File} file Media File to Save. * * @returns {Promise} Media Object Promise. */ diff --git a/utils/terms.js b/utils/terms.js index 98253862be816..12788c2512f6c 100644 --- a/utils/terms.js +++ b/utils/terms.js @@ -4,9 +4,9 @@ import { groupBy } from 'lodash'; /** - * Returns terms in a tree form - ยช - * @param {Array} flatTerms Array of terms in flat format. + * Returns terms in a tree form. + * + * @param {Array} flatTerms Array of terms in flat format. * * @returns {Array} Array of terms in tree format. */