diff --git a/blocks/api/categories.js b/blocks/api/categories.js index bf7894bbd62c3..3844c38263a10 100644 --- a/blocks/api/categories.js +++ b/blocks/api/categories.js @@ -23,7 +23,7 @@ const categories = [ /** * Returns all the block categories * - * @return {Array} Block categories + * @returns {Array} Block categories. */ export function getCategories() { return categories; diff --git a/blocks/api/factory.js b/blocks/api/factory.js index f3fb437c932e9..43d8c488e72d0 100644 --- a/blocks/api/factory.js +++ b/blocks/api/factory.js @@ -32,7 +32,8 @@ import { getBlockType, getBlockTypes } from './registration'; * * @param {String} name Block name * @param {Object} blockAttributes Block attributes - * @return {Object} Block object + * + * @returns {Object} Block object. */ export function createBlock( name, blockAttributes = {} ) { // Get the type definition associated with a registered block. @@ -67,7 +68,8 @@ export function createBlock( name, blockAttributes = {} ) { * * @param {String} sourceName Block name * @param {Boolean} isMultiBlock Array of possible block transformations - * @return {Function} Predicate that receives a block type. + * + * @returns {Function} Predicate that receives a block type. */ const isTransformForBlockSource = ( sourceName, isMultiBlock = false ) => ( transform ) => ( transform.type === 'block' && @@ -81,7 +83,8 @@ const isTransformForBlockSource = ( sourceName, isMultiBlock = false ) => ( tran * * @param {String} sourceName Block name * @param {Boolean} isMultiBlock Array of possible block transformations - * @return {Function} Predicate that receives a block type. + * + * @returns {Function} Predicate that receives a block type. */ const createIsTypeTransformableFrom = ( sourceName, isMultiBlock = false ) => ( type ) => ( !! find( @@ -94,7 +97,8 @@ const createIsTypeTransformableFrom = ( sourceName, isMultiBlock = false ) => ( * Returns an array of possible block transformations that could happen on the set of blocks received as argument. * * @param {Array} blocks Blocks array - * @return {Array} Array of possible block transformations + * + * @returns {Array} Array of possible block transformations. */ export function getPossibleBlockTransformations( blocks ) { const sourceBlock = first( blocks ); @@ -141,7 +145,8 @@ export function getPossibleBlockTransformations( blocks ) { * * @param {Array|Object} blocks Blocks array or block object * @param {string} name Block name - * @return {Array} Array of blocks + * + * @returns {Array} Array of blocks. */ export function switchToBlockType( blocks, name ) { const blocksArray = castArray( blocks ); @@ -218,7 +223,8 @@ export function switchToBlockType( blocks, name ) { * * @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 - * @return {Object} A reusable block object + * + * @returns {Object} A reusable block object. */ export function createReusableBlock( type, attributes ) { return { diff --git a/blocks/api/parser.js b/blocks/api/parser.js index 82add30a463e8..2de25032cb4be 100644 --- a/blocks/api/parser.js +++ b/blocks/api/parser.js @@ -21,7 +21,8 @@ import { attr, prop, html, text, query, node, children } from './matchers'; * * @param {*} value Original value * @param {String} type Type to coerce - * @return {*} Coerced value + * + * @returns {*} Coerced value. */ export function asType( value, type ) { switch ( type ) { @@ -56,7 +57,8 @@ export function asType( value, type ) { * Returns an hpq matcher given a source object * * @param {Object} sourceConfig Attribute Source object - * @return {Function} hpq Matcher + * + * @returns {Function} hpq Matcher. */ export function matcherFromSource( sourceConfig ) { switch ( sourceConfig.source ) { @@ -90,7 +92,7 @@ export function matcherFromSource( sourceConfig ) { * @param {string} innerHTML Block's raw content * @param {Object} commentAttributes Block's comment attributes * - * @return {*} Attribute value + * @returns {*} Attribute value. */ export function getBlockAttribute( attributeKey, attributeSchema, innerHTML, commentAttributes ) { let value; @@ -119,7 +121,8 @@ export function getBlockAttribute( attributeKey, attributeSchema, innerHTML, com * @param {?Object} blockType Block type * @param {string} innerHTML Raw block content * @param {?Object} attributes Known block attributes (from delimiters) - * @return {Object} All block attributes + * + * @returns {Object} All block attributes. */ export function getBlockAttributes( blockType, innerHTML, attributes ) { const blockAttributes = mapValues( blockType.attributes, ( attributeSchema, attributeKey ) => { @@ -135,7 +138,8 @@ export function getBlockAttributes( blockType, innerHTML, attributes ) { * @param {?Object} blockType Block type * @param {string} innerHTML Raw block content * @param {?Object} attributes Known block attributes (from delimiters) - * @return {Object} Block attributes + * + * @returns {Object} Block attributes. */ export function getAttributesFromDeprecatedVersion( blockType, innerHTML, attributes ) { if ( ! blockType.deprecated ) { @@ -161,7 +165,8 @@ export function getAttributesFromDeprecatedVersion( blockType, innerHTML, attrib * @param {?String} name Block type name * @param {String} innerHTML Raw block content * @param {?Object} attributes Attributes obtained from block delimiters - * @return {?Object} An initialized block object (if possible) + * + * @returns {?Object} An initialized block object (if possible). */ export function createBlockWithFallback( name, innerHTML, attributes ) { // Use type from block content, otherwise find unknown handler. @@ -228,7 +233,8 @@ 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 - * @return {Array} Block list + * + * @returns {Array} Block list. */ export function parseWithGrammar( content ) { return grammarParse( content ).reduce( ( memo, blockNode ) => { diff --git a/blocks/api/raw-handling/index.js b/blocks/api/raw-handling/index.js index 21c1e25cd7bbf..ccff345ba79ea 100644 --- a/blocks/api/raw-handling/index.js +++ b/blocks/api/raw-handling/index.js @@ -35,7 +35,8 @@ import shortcodeConverter from './shortcode-converter'; * * '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. - * @return {Array|String} A list of blocks or a string, depending on `handlerMode`. + * + * @returns {Array|String} A list of blocks or a string, depending on `handlerMode`. */ export default function rawHandler( { HTML, plainText = '', mode = 'AUTO', tagName } ) { // First of all, strip any meta tags. diff --git a/blocks/api/raw-handling/utils.js b/blocks/api/raw-handling/utils.js index 777c0796eaafb..fd3678032d618 100644 --- a/blocks/api/raw-handling/utils.js +++ b/blocks/api/raw-handling/utils.js @@ -84,7 +84,9 @@ export function isAttributeWhitelisted( tag, attribute ) { * * @param {String} nodeName Node name. * @param {String} tagName Tag name. - * @return {Boolean} True if nodeName is inline in the context of tagName and false otherwise. + * + * @returns {Boolean} True if nodeName is inline in the context of tagName and + * false otherwise. */ function isInlineForTag( nodeName, tagName ) { if ( ! tagName || ! nodeName ) { @@ -219,7 +221,8 @@ export function deepFilterNodeList( nodeList, filters, doc ) { * * @param {String} HTML The HTML to filter. * @param {Array} filters An array of functions that can mutate with the provided node. - * @return {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 22ad06b0e5a77..9723d38fdd3f1 100644 --- a/blocks/api/registration.js +++ b/blocks/api/registration.js @@ -45,8 +45,9 @@ let defaultBlockName; * * @param {string} name Block name * @param {Object} settings Block settings - * @return {?WPBlock} The block, if it has been successfully - * registered; otherwise `undefined`. + * + * @returns {?WPBlock} The block, if it has been successfully registered; + * otherwise `undefined`. */ export function registerBlockType( name, settings ) { settings = { @@ -128,8 +129,9 @@ export function registerBlockType( name, settings ) { * Unregisters a block. * * @param {string} name Block name - * @return {?WPBlock} The previous block value, if it has been - * successfully unregistered; otherwise `undefined`. + * + * @returns {?WPBlock} The previous block value, if it has been successfully + * unregistered; otherwise `undefined`. */ export function unregisterBlockType( name ) { if ( ! blocks[ name ] ) { @@ -156,7 +158,7 @@ export function setUnknownTypeHandlerName( name ) { * Retrieves name of block handling unknown block types, or undefined if no * handler has been defined. * - * @return {?string} Blog name + * @returns {?string} Blog name. */ export function getUnknownTypeHandlerName() { return unknownTypeHandlerName; @@ -174,7 +176,7 @@ export function setDefaultBlockName( name ) { /** * Retrieves the default block name * - * @return {?string} Blog name + * @returns {?string} Blog name. */ export function getDefaultBlockName() { return defaultBlockName; @@ -184,7 +186,8 @@ export function getDefaultBlockName() { * Returns a registered block type. * * @param {string} name Block name - * @return {?Object} Block type + * + * @returns {?Object} Block type. */ export function getBlockType( name ) { return blocks[ name ]; @@ -193,7 +196,7 @@ export function getBlockType( name ) { /** * Returns all registered blocks. * - * @return {Array} Block settings + * @returns {Array} Block settings. */ export function getBlockTypes() { return Object.values( blocks ); @@ -206,7 +209,8 @@ export function getBlockTypes() { * @param {String} feature Feature to test * @param {Boolean} defaultSupports Whether feature is supported by * default if not explicitly defined - * @return {Boolean} Whether block supports feature + * + * @returns {Boolean} Whether block supports feature. */ export function hasBlockSupport( nameOrType, feature, defaultSupports ) { const blockType = 'string' === typeof nameOrType ? @@ -225,7 +229,8 @@ export function hasBlockSupport( nameOrType, feature, defaultSupports ) { * API. * * @param {Object} blockOrType Block or Block Type to test - * @return {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 24b903997c3fc..a539058e0d254 100644 --- a/blocks/api/serializer.js +++ b/blocks/api/serializer.js @@ -19,7 +19,8 @@ import { getBlockType, getUnknownTypeHandlerName } from './registration'; * Returns the block's default classname from its name * * @param {String} blockName The block name - * @return {string} The block's default class + * + * @returns {string} The block's default class. */ export function getBlockDefaultClassname( blockName ) { // Drop common prefixes: 'core/' or 'core-' (in 'core-embed/') @@ -32,7 +33,8 @@ export function getBlockDefaultClassname( blockName ) { * * @param {Object} blockType Block type * @param {Object} attributes Block attributes - * @return {Object|string} Save content + * + * @returns {Object|string} Save content. */ export function getSaveElement( blockType, attributes ) { const { save } = blockType; @@ -70,7 +72,8 @@ export function getSaveElement( blockType, attributes ) { * * @param {Object} blockType Block type * @param {Object} attributes Block attributes - * @return {string} Save content + * + * @returns {string} Save content. */ export function getSaveContent( blockType, attributes ) { const saveElement = getSaveElement( blockType, attributes ); @@ -97,7 +100,8 @@ export function getSaveContent( blockType, attributes ) { * * @param {Object} allAttributes Attributes from in-memory block data * @param {Object} blockType Block type - * @returns {Object} Subset of attributes for comment serialization + * + * @returns {Object} Subset of attributes for comment serialization. */ export function getCommentAttributes( allAttributes, blockType ) { const attributes = reduce( blockType.attributes, ( result, attributeSchema, key ) => { @@ -140,7 +144,8 @@ export function serializeAttributes( attrs ) { * block serialization. * * @param {String} content Original HTML - * @return {String} Beautiful HTML + * + * @returns {String} Beautiful HTML. */ export function getBeautifulContent( content ) { return beautifyHtml( content, { @@ -152,7 +157,8 @@ export function getBeautifulContent( content ) { /** * Given a block object, returns the Block's Inner HTML markup * @param {Object} block Block Object - * @return {String} HTML + * + * @returns {String} HTML. */ export function getBlockContent( block ) { const blockType = getBlockType( block.name ); @@ -175,7 +181,8 @@ export function getBlockContent( block ) { * @param {String} rawBlockName Block name * @param {Object} attributes Block attributes * @param {String} content Block save content - * @return {String} Comment-delimited block content + * + * @returns {String} Comment-delimited block content. */ export function getCommentDelimitedContent( rawBlockName, attributes, content ) { const serializedAttributes = ! isEmpty( attributes ) ? @@ -203,7 +210,8 @@ export function getCommentDelimitedContent( rawBlockName, attributes, content ) * serialized attributes and content form from the current state of the block. * * @param {Object} block Block instance - * @return {String} Serialized block + * + * @returns {String} Serialized block. */ export function serializeBlock( block ) { const blockName = block.name; @@ -237,7 +245,8 @@ export function serializeBlock( block ) { * Takes a block or set of blocks and returns the serialized post content. * * @param {Array} blocks Block(s) to serialize - * @return {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 2155bf3a70786..511462d3e2160 100644 --- a/blocks/api/validation.js +++ b/blocks/api/validation.js @@ -133,7 +133,8 @@ const log = ( () => { * Creates a logger with block validation prefix. * * @param {Function} logger Original logger function - * @return {Function} Augmented logger function + * + * @returns {Function} Augmented logger function. */ function createLogger( logger ) { // In test environments, pre-process the sprintf message to improve @@ -160,7 +161,8 @@ const log = ( () => { * whitespace, ignoring leading or trailing whitespace. * * @param {String} text Original text - * @return {String[]} Text pieces split on whitespace + * + * @returns {String[]} Text pieces split on whitespace. */ export function getTextPiecesSplitOnWhitespace( text ) { return text.trim().split( REGEXP_WHITESPACE ); @@ -171,7 +173,8 @@ export function getTextPiecesSplitOnWhitespace( text ) { * whitespace is collapsed to a single space. * * @param {String} text Original text - * @return {String} Trimmed text with consecutive whitespace collapsed + * + * @returns {String} Trimmed text with consecutive whitespace collapsed. */ export function getTextWithCollapsedWhitespace( text ) { return getTextPiecesSplitOnWhitespace( text ).join( ' ' ); @@ -185,7 +188,8 @@ export function getTextWithCollapsedWhitespace( text ) { * @see MEANINGFUL_ATTRIBUTES * * @param {Object} token StartTag token - * @return {Array[]} Attribute pairs + * + * @returns {Array[]} Attribute pairs. */ export function getMeaningfulAttributePairs( token ) { return token.attributes.filter( ( pair ) => { @@ -204,7 +208,8 @@ export function getMeaningfulAttributePairs( token ) { * * @param {Object} actual Actual token * @param {Object} expected Expected token - * @return {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 @@ -225,7 +230,8 @@ export function isEqualTextTokensWithCollapsedWhitespace( actual, expected ) { * comparison. * * @param {String} value Style value - * @return {String} Normalized style value + * + * @returns {String} Normalized style value. */ export function getNormalizedStyleValue( value ) { return value @@ -237,7 +243,8 @@ export function getNormalizedStyleValue( value ) { * Given a style attribute string, returns an object of style properties. * * @param {String} text Style attribute - * @return {Object} Style properties + * + * @returns {Object} Style properties. */ export function getStyleProperties( text ) { const pairs = text @@ -282,7 +289,8 @@ export const isEqualAttributesOfName = { * * @param {Array[]} actual Actual attributes tuples * @param {Array[]} expected Expected attributes tuples - * @return {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 @@ -350,7 +358,8 @@ export const isEqualTokensOfType = { * Mutates the tokens array. * * @param {Object[]} tokens Set of tokens to search - * @return {Object} Next non-whitespace token + * + * @returns {Object} Next non-whitespace token. */ export function getNextNonWhitespaceToken( tokens ) { let token; @@ -371,7 +380,8 @@ export function getNextNonWhitespaceToken( tokens ) { * * @param {String} actual Actual HTML string * @param {String} expected Expected HTML string - * @return {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 @@ -421,7 +431,8 @@ export function isEquivalentHTML( actual, expected ) { * @param {String} innerHTML Original block content * @param {String} blockType Block type * @param {Object} attributes Parsed block attributes - * @return {Boolean} Whether block is valid + * + * @returns {Boolean} Whether block is valid. */ export function isValidBlock( innerHTML, blockType, attributes ) { let saveContent; diff --git a/blocks/hooks/anchor.js b/blocks/hooks/anchor.js index 161ab2fee1496..71ea806285795 100644 --- a/blocks/hooks/anchor.js +++ b/blocks/hooks/anchor.js @@ -28,7 +28,8 @@ const ANCHOR_REGEX = /[\s#]/g; * of the first node * * @param {Object} settings Original block settings - * @return {Object} Filtered block settings + * + * @returns {Object} Filtered block settings. */ export function addAttribute( settings ) { if ( hasBlockSupport( settings, 'anchor' ) ) { @@ -51,7 +52,8 @@ export function addAttribute( settings ) { * assigning the anchor ID, if block supports anchor. * * @param {function|Component} BlockEdit Original component - * @return {function} Wrapped component + * + * @returns {function} Wrapped component. */ export function withInspectorControl( BlockEdit ) { const WrappedBlockEdit = ( props ) => { @@ -86,7 +88,8 @@ export function withInspectorControl( BlockEdit ) { * @param {Object} extraProps Additional props applied to save element * @param {Object} blockType Block type * @param {Object} attributes Current block attributes - * @return {Object} Filtered props applied to save element + * + * @returns {Object} Filtered props applied to save element. */ export function addSaveProps( extraProps, blockType, attributes ) { if ( hasBlockSupport( blockType, 'anchor' ) ) { diff --git a/blocks/hooks/custom-class-name.js b/blocks/hooks/custom-class-name.js index 3b9585a57388f..0e025c1da79ce 100644 --- a/blocks/hooks/custom-class-name.js +++ b/blocks/hooks/custom-class-name.js @@ -22,7 +22,8 @@ import InspectorControls from '../inspector-controls'; * of the first node * * @param {Object} settings Original block settings - * @return {Object} Filtered block settings + * + * @returns {Object} Filtered block settings. */ export function addAttribute( settings ) { if ( hasBlockSupport( settings, 'customClassName', true ) ) { @@ -42,7 +43,8 @@ export function addAttribute( settings ) { * assigning the custom class name, if block supports custom class name. * * @param {function|Component} BlockEdit Original component - * @return {function} Wrapped component + * + * @returns {function} Wrapped component. */ export function withInspectorControl( BlockEdit ) { const WrappedBlockEdit = ( props ) => { @@ -76,7 +78,8 @@ export function withInspectorControl( BlockEdit ) { * @param {Object} extraProps Additional props applied to save element * @param {Object} blockType Block type * @param {Object} attributes Current block attributes - * @return {Object} Filtered props applied to save element + * + * @returns {Object} Filtered props applied to save element. */ export function addSaveProps( extraProps, blockType, attributes ) { if ( hasBlockSupport( blockType, 'customClassName', true ) && attributes.className ) { diff --git a/blocks/hooks/generated-class-name.js b/blocks/hooks/generated-class-name.js index 6a9740b3eb924..ef1d87f64e4d9 100644 --- a/blocks/hooks/generated-class-name.js +++ b/blocks/hooks/generated-class-name.js @@ -20,7 +20,8 @@ import { hasBlockSupport, getBlockDefaultClassname } from '../api'; * * @param {Object} extraProps Additional props applied to save element * @param {Object} blockType Block type - * @return {Object} Filtered props applied to save element + * + * @returns {Object} Filtered props applied to save element. */ export function addGeneratedClassName( extraProps, blockType ) { // Adding the generated className diff --git a/blocks/hooks/matchers.js b/blocks/hooks/matchers.js index 374411d39810e..6f277fd2ce0df 100644 --- a/blocks/hooks/matchers.js +++ b/blocks/hooks/matchers.js @@ -79,7 +79,8 @@ export const node = ( selector ) => () => { * Resolve the matchers attributes for backwards compatibilty * * @param {Object} settings Original block settings - * @return {Object} Filtered block settings + * + * @returns {Object} Filtered block settings. */ export function resolveAttributes( settings ) { // Resolve deprecated attributes diff --git a/components/higher-order/with-api-data/request.js b/components/higher-order/with-api-data/request.js index 627fbcba5c16a..70747e693956e 100644 --- a/components/higher-order/with-api-data/request.js +++ b/components/higher-order/with-api-data/request.js @@ -46,7 +46,8 @@ export const cache = mapKeys( * @see https://xhr.spec.whatwg.org/#the-getallresponseheaders()-method * * @param {XMLHttpRequest} xhr XMLHttpRequest object - * @return {Array[]} Array of header tuples + * + * @returns {Array[]} Array of header tuples. */ export function getResponseHeaders( xhr ) { // 'date: Tue, 22 Aug 2017 18:45:28 GMT↵server: nginx' @@ -64,7 +65,8 @@ export function getResponseHeaders( xhr ) { * undefined otherwise. * * @param {Object} request Request object (path, method) - * @return {?Object} Response object (body, headers) + * + * @returns {?Object} Response object (body, headers). */ export function getCachedResponse( request ) { if ( isRequestMethod( request, 'GET' ) ) { diff --git a/components/higher-order/with-api-data/routes.js b/components/higher-order/with-api-data/routes.js index 752cb54ad68f2..c218cb2b0a2d4 100644 --- a/components/higher-order/with-api-data/routes.js +++ b/components/higher-order/with-api-data/routes.js @@ -21,7 +21,8 @@ const RE_NAMED_SUBPATTERN = /\(\?P?[<']\w+[>'](.*?)\)/g; * slash, allowing query parameters, but otherwise enforcing strict equality. * * @param {String} pattern PCRE regular expression string - * @return {RegExp} Equivalent JavaScript RegExp + * + * @returns {RegExp} Equivalent JavaScript RegExp. */ export function getNormalizedRegExp( pattern ) { pattern = pattern.replace( RE_NAMED_SUBPATTERN, '($1)' ); @@ -34,7 +35,8 @@ export function getNormalizedRegExp( pattern ) { * * @param {String} pattern PCRE route path pattern * @param {String} path URL path - * @return {Boolean} Whether path is a match + * + * @returns {Boolean} Whether path is a match. */ export function isRouteMatch( pattern, path ) { return getNormalizedRegExp( pattern ).test( path ); @@ -45,7 +47,8 @@ export function isRouteMatch( pattern, path ) { * * @param {Object} schema REST schema * @param {String} path URL path - * @return {?Object} REST route + * + * @returns {?Object} REST route. */ export const getRoute = createSelector( ( schema, path ) => { return find( schema.routes, ( route, pattern ) => { diff --git a/components/higher-order/with-filters/index.js b/components/higher-order/with-filters/index.js index 34eeb87340542..56ab88a7b75c7 100644 --- a/components/higher-order/with-filters/index.js +++ b/components/higher-order/with-filters/index.js @@ -9,7 +9,8 @@ import { applyFilters } from '@wordpress/hooks'; * Filters get applied when the original component is about to be mounted. * * @param {String} hookName Hook name exposed to be used by filters. - * @return {Function} Higher-order component factory. + * + * @returns {Function} Higher-order component factory. */ export default function withFilters( hookName ) { return ( OriginalComponent ) => { diff --git a/components/higher-order/with-focus-return/index.js b/components/higher-order/with-focus-return/index.js index 615205c75d247..9fc822117213a 100644 --- a/components/higher-order/with-focus-return/index.js +++ b/components/higher-order/with-focus-return/index.js @@ -10,7 +10,7 @@ import { Component } from '@wordpress/element'; * * @param {WPElement} WrappedComponent The disposable component * - * @return {Component} Component with the focus restauration behaviour + * @returns {Component} Component with the focus restauration behaviour. */ function withFocusReturn( WrappedComponent ) { return class extends Component { diff --git a/components/higher-order/with-instance-id/index.js b/components/higher-order/with-instance-id/index.js index 400e891f6113d..dffd7abe9f05a 100644 --- a/components/higher-order/with-instance-id/index.js +++ b/components/higher-order/with-instance-id/index.js @@ -8,7 +8,7 @@ import { Component } from '@wordpress/element'; * * @param {WPElement} WrappedComponent The wrapped component * - * @return {Component} Component with an instanceId prop. + * @returns {Component} Component with an instanceId prop. */ function withInstanceId( WrappedComponent ) { let instances = 0; diff --git a/components/higher-order/with-spoken-messages/index.js b/components/higher-order/with-spoken-messages/index.js index 6b5895983017d..1930adcb5e833 100644 --- a/components/higher-order/with-spoken-messages/index.js +++ b/components/higher-order/with-spoken-messages/index.js @@ -14,7 +14,7 @@ import { speak } from '@wordpress/a11y'; * * @param {WPElement} WrappedComponent The wrapped component * - * @return {Component} Component with an instanceId prop. + * @returns {Component} Component with an instanceId prop. */ function withSpokenMessages( WrappedComponent ) { return class extends Component { diff --git a/components/higher-order/with-state/index.js b/components/higher-order/with-state/index.js index 3e2bea08a32da..dc5a3e537f55f 100644 --- a/components/higher-order/with-state/index.js +++ b/components/higher-order/with-state/index.js @@ -8,7 +8,8 @@ import { Component, getWrapperDisplayName } from '@wordpress/element'; * via props. * * @param {?Object} initialState Optional initial state of the component - * @return {Component} Wrapped component + * + * @returns {Component} Wrapped component. */ function withState( initialState = {} ) { return ( OriginalComponent ) => { diff --git a/data/index.js b/data/index.js index 8cba209ecbf59..1cf4a779fd01a 100644 --- a/data/index.js +++ b/data/index.js @@ -22,7 +22,7 @@ const store = createStore( initialReducer, {}, flowRight( enhancers ) ); * @param {String} key Reducer key * @param {Object} reducer Reducer function * - * @return {Object} Store Object + * @returns {Object} Store Object. */ export function registerReducer( key, reducer ) { reducers[ key ] = reducer; diff --git a/date/index.js b/date/index.js index 5b1dfb7f1fc8c..ab49f76326110 100644 --- a/date/index.js +++ b/date/index.js @@ -44,7 +44,8 @@ const formatMap = { * Gets the ordinal suffix. * * @param {moment} momentDate Moment instance. - * @return {string} Formatted date. + * + * @returns {string} Formatted date. */ S( momentDate ) { // Do - D @@ -58,7 +59,8 @@ const formatMap = { * Gets the day of the year (zero-indexed). * * @param {moment} momentDate Moment instance. - * @return {string} Formatted date. + * + * @returns {string} Formatted date. */ z( momentDate ) { // DDD - 1 @@ -77,7 +79,8 @@ const formatMap = { * Gets the days in the month. * * @param {moment} momentDate Moment instance. - * @return {string} Formatted date. + * + * @returns {string} Formatted date. */ t( momentDate ) { return momentDate.daysInMonth(); @@ -88,7 +91,8 @@ const formatMap = { * Gets whether the current year is a leap year. * * @param {moment} momentDate Moment instance. - * @return {string} Formatted date. + * + * @returns {string} Formatted date. */ L( momentDate ) { return momentDate.isLeapYear() ? '1' : '0'; @@ -104,7 +108,8 @@ const formatMap = { * Gets the current time in Swatch Internet Time (.beats). * * @param {moment} momentDate Moment instance. - * @return {string} Formatted date. + * + * @returns {string} Formatted date. */ B( momentDate ) { const timezoned = moment( momentDate ).utcOffset( 60 ); @@ -134,7 +139,8 @@ const formatMap = { * Gets whether the timezone is in DST currently. * * @param {moment} momentDate Moment instance. - * @return {string} Formatted date. + * + * @returns {string} Formatted date. */ I( momentDate ) { return momentDate.isDST() ? '1' : '0'; @@ -146,7 +152,8 @@ const formatMap = { * Gets the timezone offset in seconds. * * @param {moment} momentDate Moment instance. - * @return {string} Formatted date. + * + * @returns {string} Formatted date. */ Z( momentDate ) { // Timezone offset in seconds. @@ -218,7 +225,8 @@ function setupLocale( settings ) { * See php.net/date * @param {(Date|string|moment|null)} dateValue Date object or string, * parsable by moment.js. - * @return {string} Formatted date. + * + * @returns {string} Formatted date. */ export function format( dateFormat, dateValue = new Date() ) { let i, char; @@ -259,7 +267,7 @@ export function format( dateFormat, dateValue = new Date() ) { * @param {(Date|string|moment|null)} dateValue Date object or string, * parsable by moment.js. * - * @return {string} Formatted date. + * @returns {string} Formatted date. */ export function date( dateFormat, dateValue = new Date() ) { const offset = window._wpDateSettings.timezone.offset * HOUR_IN_MINUTES; @@ -275,7 +283,7 @@ export function date( dateFormat, dateValue = new Date() ) { * @param {(Date|string|moment|null)} dateValue Date object or string, * parsable by moment.js. * - * @return {string} Formatted date. + * @returns {string} Formatted date. */ export function gmdate( dateFormat, dateValue = new Date() ) { const dateMoment = moment( dateValue ).utc(); @@ -292,7 +300,7 @@ export function gmdate( dateFormat, dateValue = new Date() ) { * @param {boolean} gmt True for GMT/UTC, false for * site's timezone. * - * @return {string} Formatted date. + * @returns {string} Formatted date. */ export function dateI18n( dateFormat, dateValue = new Date(), gmt = false ) { // Defaults. diff --git a/editor/components/block-list/block.js b/editor/components/block-list/block.js index 529e9e082f650..02775e3582857 100644 --- a/editor/components/block-list/block.js +++ b/editor/components/block-list/block.js @@ -71,7 +71,8 @@ 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 - * @return {?Element} Scrollable container node, if found + * + * @returns {?Element} Scrollable container node, if found. */ function getScrollContainer( node ) { if ( ! node ) { diff --git a/editor/components/block-mover/mover-label.js b/editor/components/block-mover/mover-label.js index 1b09cce174259..2c0f2d7d5d3fc 100644 --- a/editor/components/block-mover/mover-label.js +++ b/editor/components/block-mover/mover-label.js @@ -14,7 +14,8 @@ import { __, sprintf } from '@wordpress/i18n'; * @param {boolean} isLast This is the last block. * @param {number} dir Direction of movement (> 0 is considered to be going * down, < 0 is up). - * @return {string} Label for the block movement controls. + * + * @returns {string} Label for the block movement controls. */ export function getBlockMoverLabel( selectedCount, type, firstIndex, isFirst, isLast, dir ) { const position = ( firstIndex + 1 ); @@ -74,7 +75,8 @@ export function getBlockMoverLabel( selectedCount, type, firstIndex, isFirst, is * @param {boolean} isLast This is the last block. * @param {number} dir Direction of movement (> 0 is considered to be going * down, < 0 is up). - * @return {string} Label for the block movement controls. + * + * @returns {string} Label for the block movement controls. */ export function getMultiBlockMoverLabel( selectedCount, firstIndex, isFirst, isLast, dir ) { const position = ( firstIndex + 1 ); diff --git a/editor/index.js b/editor/index.js index 2cd98d2b73bfb..5e5f1115c3e65 100644 --- a/editor/index.js +++ b/editor/index.js @@ -78,7 +78,8 @@ export function recreateEditorInstance( target, settings ) { * @param {String} id Unique identifier for editor instance * @param {Object} post API entity for post to edit * @param {?Object} settings Editor settings object - * @return {Object} Editor interface + * + * @returns {Object} Editor interface. */ export function createEditorInstance( id, post, settings ) { const target = document.getElementById( id ); diff --git a/editor/store/actions.js b/editor/store/actions.js index 0e4b6cd723edf..506c72414835d 100644 --- a/editor/store/actions.js +++ b/editor/store/actions.js @@ -10,7 +10,7 @@ import { partial, castArray } from 'lodash'; * * @param {Object} post Post object * @param {Object} settings Editor settings object - * @return {Object} Action object + * @returns {Object} Action object */ export function setupEditor( post, settings ) { return { @@ -25,7 +25,8 @@ export function setupEditor( post, settings ) { * post has been received, either by initialization or save. * * @param {Object} post Post object - * @return {Object} Action object + * + * @returns {Object} Action object. */ export function resetPost( post ) { return { @@ -39,7 +40,8 @@ export function resetPost( post ) { * new post with specified edits which should be considered non-dirtying. * * @param {Object} edits Edited attributes object - * @return {Object} Action object + * + * @returns {Object} Action object. */ export function setupNewPost( edits ) { return { @@ -54,7 +56,8 @@ export function setupNewPost( edits ) { * content reflected as an edit in state. * * @param {Array} blocks Array of blocks - * @return {Object} Action object + * + * @returns {Object} Action object. */ export function resetBlocks( blocks ) { return { @@ -69,7 +72,8 @@ export function resetBlocks( blocks ) { * * @param {String} uid Block UID * @param {Object} attributes Block attributes to be merged - * @return {Object} Action object + * + * @returns {Object} Action object. */ export function updateBlockAttributes( uid, attributes ) { return { @@ -85,7 +89,8 @@ export function updateBlockAttributes( uid, attributes ) { * * @param {String} uid Block UID * @param {Object} updates Block attributes to be merged - * @return {Object} Action object + * + * @returns {Object} Action object. */ export function updateBlock( uid, updates ) { return { @@ -140,7 +145,8 @@ export function clearSelectedBlock() { * Returns an action object that enables or disables block selection * * @param {boolean} [isSelectionEnabled=true] Whether block selection should be enabled - * @return {Object} Action object + + * @returns {Object} Action object. */ export function toggleSelection( isSelectionEnabled = true ) { return { @@ -155,7 +161,8 @@ export function toggleSelection( isSelectionEnabled = true ) { * * @param {(String|String[])} uids Block UID(s) to replace * @param {(Object|Object[])} blocks Replacement block(s) - * @return {Object} Action object + * + * @returns {Object} Action object. */ export function replaceBlocks( uids, blocks ) { return { @@ -171,7 +178,8 @@ export function replaceBlocks( uids, blocks ) { * * @param {(String|String[])} uid Block UID(s) to replace * @param {(Object|Object[])} block Replacement block(s) - * @return {Object} Action object + * + * @returns {Object} Action object. */ export function replaceBlock( uid, block ) { return replaceBlocks( uid, block ); @@ -193,7 +201,8 @@ export function insertBlocks( blocks, position ) { * Returns an action object showing the insertion point at a given index * * @param {Number?} index Index of the insertion point - * @return {Object} Action object + * + * @returns {Object} Action object. */ export function showInsertionPoint( index ) { return { @@ -205,7 +214,7 @@ export function showInsertionPoint( index ) { /** * Returns an action object hiding the insertion point * - * @return {Object} Action object + * @returns {Object} Action object. */ export function hideInsertionPoint() { return { @@ -244,7 +253,7 @@ export function mergeBlocks( blockA, blockB ) { /** * Returns an action object used in signalling that the post should autosave. * - * @return {Object} Action object + * @returns {Object} Action object. */ export function autosave() { return { @@ -256,7 +265,7 @@ export function autosave() { * Returns an action object used in signalling that undo history should * restore last popped state. * - * @return {Object} Action object + * @returns {Object} Action object. */ export function redo() { return { type: 'REDO' }; @@ -265,7 +274,7 @@ export function redo() { /** * Returns an action object used in signalling that undo history should pop. * - * @return {Object} Action object + * @returns {Object} Action object. */ export function undo() { return { type: 'UNDO' }; @@ -276,7 +285,8 @@ export function undo() { * corresponding to the specified UID set are to be removed. * * @param {String[]} uids Block UIDs - * @return {Object} Action object + * + * @returns {Object} Action object. */ export function removeBlocks( uids ) { return { @@ -290,7 +300,8 @@ export function removeBlocks( uids ) { * specified UID is to be removed. * * @param {String} uid Block UID - * @return {Object} Action object + * + * @returns {Object} Action object. */ export function removeBlock( uid ) { return removeBlocks( [ uid ] ); @@ -300,7 +311,8 @@ export function removeBlock( uid ) { * Returns an action object used to toggle the block editing mode (visual/html) * * @param {String} uid Block UID - * @return {Object} Action object + * + * @returns {Object} Action object. */ export function toggleBlockMode( uid ) { return { @@ -312,7 +324,7 @@ export function toggleBlockMode( uid ) { /** * Returns an action object used in signalling that the user has begun to type. * - * @return {Object} Action object + * @returns {Object} Action object. */ export function startTyping() { return { @@ -323,7 +335,7 @@ export function startTyping() { /** * Returns an action object used in signalling that the user has stopped typing. * - * @return {Object} Action object + * @returns {Object} Action object. */ export function stopTyping() { return { @@ -336,7 +348,8 @@ export function stopTyping() { * * @param {String} sidebar Name of the sidebar to toggle (desktop, mobile or publish) * @param {Boolean?} forcedValue Force a sidebar state - * @return {Object} Action object + * + * @returns {Object} Action object. */ export function toggleSidebar( sidebar, forcedValue ) { return { @@ -350,7 +363,8 @@ export function toggleSidebar( sidebar, forcedValue ) { * Returns an action object used in signalling that the user switched the active sidebar tab panel * * @param {String} panel The panel name - * @return {Object} Action object + * + * @returns {Object} Action object. */ export function setActivePanel( panel ) { return { @@ -363,7 +377,8 @@ export function setActivePanel( panel ) { * Returns an action object used in signalling that the user toggled a sidebar panel * * @param {String} panel The panel name - * @return {Object} Action object + * + * @returns {Object} Action object. */ export function toggleSidebarPanel( panel ) { return { @@ -381,7 +396,7 @@ export function toggleSidebarPanel( panel ) { * `id` (string; default auto-generated) * `isDismissible` (boolean; default `true`) * - * @return {Object} Action object + * @returns {Object} Action object. */ export function createNotice( status, content, options = {} ) { const { @@ -406,7 +421,7 @@ export function createNotice( status, content, options = {} ) { * * @param {String} id The notice id * - * @return {Object} Action object + * @returns {Object} Action object. */ export function removeNotice( id ) { return { @@ -427,7 +442,7 @@ export function removeNotice( id ) { * * @param {Object} metaBoxes Whether meta box locations are active. * - * @return {Object} Action object + * @returns {Object} Action object. */ export function initializeMetaBoxState( metaBoxes ) { return { @@ -441,7 +456,7 @@ export function initializeMetaBoxState( metaBoxes ) { * * @param {String} location Location of meta box: 'normal', 'side' or 'advanced'. * - * @return {Object} Action object + * @returns {Object} Action object. */ export function handleMetaBoxReload( location ) { return { @@ -455,7 +470,7 @@ export function handleMetaBoxReload( location ) { * * @param {String} location Location of meta box: 'normal', 'side' or 'advanced'. * - * @return {Object} Action object + * @returns {Object} Action object. */ export function metaBoxLoaded( location ) { return { @@ -469,7 +484,7 @@ export function metaBoxLoaded( location ) { * * @param {Array} locations Locations of meta boxes: ['normal', 'side', 'advanced' ]. * - * @return {Object} Action object + * @returns {Object} Action object. */ export function requestMetaBoxUpdates( locations ) { return { @@ -484,7 +499,7 @@ export function requestMetaBoxUpdates( locations ) { * @param {String} location Location of meta box: 'normal', 'side' or 'advanced'. * @param {Boolean} hasChanged Whether the meta box has changed. * - * @return {Object} Action object + * @returns {Object} Action object. */ export function metaBoxStateChanged( location, hasChanged ) { return { @@ -499,7 +514,7 @@ export function metaBoxStateChanged( location, hasChanged ) { * * @param {String} feature Featurre name. * - * @return {Object} Action object + * @returns {Object} Action object. */ export function toggleFeature( feature ) { return { @@ -518,7 +533,8 @@ export const createWarningNotice = partial( createNotice, 'warning' ); * 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 - * @return {Object} Action object + * + * @returns {Object} Action object. */ export function fetchReusableBlocks( id ) { return { @@ -532,7 +548,8 @@ export function fetchReusableBlocks( id ) { * * @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 - * @return {Object} Action object + * + * @returns {Object} Action object. */ export function updateReusableBlock( id, reusableBlock ) { return { @@ -547,7 +564,8 @@ export function updateReusableBlock( id, reusableBlock ) { * to the REST API. * * @param {Object} id The ID of the reusable block to save - * @return {Object} Action object + * + * @returns {Object} Action object. */ export function saveReusableBlock( id ) { return { @@ -558,9 +576,10 @@ 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. - * @return {Object} Action object. + * + * @returns {Object} Action object. */ export function deleteReusableBlock( id ) { return { @@ -574,7 +593,8 @@ export function deleteReusableBlock( id ) { * block. * * @param {Object} uid The ID of the block to attach - * @return {Object} Action object + * + * @returns {Object} Action object. */ export function convertBlockToStatic( uid ) { return { @@ -588,7 +608,8 @@ export function convertBlockToStatic( uid ) { * block. * * @param {Object} uid The ID of the block to detach - * @return {Object} Action object + * + * @returns {Object} Action object. */ export function convertBlockToReusable( uid ) { return { diff --git a/editor/store/middlewares.js b/editor/store/middlewares.js index 9e564c23b446e..f1a4e0c593528 100644 --- a/editor/store/middlewares.js +++ b/editor/store/middlewares.js @@ -16,7 +16,7 @@ import effects from './effects'; * * @param {Object} store Store Object * - * @return {Object} Update Store Object + * @returns {Object} Update Store Object. */ function applyMiddlewares( store ) { const middlewares = [ diff --git a/editor/store/persist.js b/editor/store/persist.js index 25ff6603d1461..8c50f9c8b641c 100644 --- a/editor/store/persist.js +++ b/editor/store/persist.js @@ -9,7 +9,7 @@ import { get } from 'lodash'; * @param {Function} reducer The reducer to enhance * @param {String} reducerKey The reducer key to persist * - * @return {Function} Enhanced reducer + * @returns {Function} Enhanced reducer. */ export function withRehydratation( reducer, reducerKey ) { // EnhancedReducer with auto-rehydration diff --git a/editor/store/reducer.js b/editor/store/reducer.js index b1f346f4e3ad6..d50531896b461 100644 --- a/editor/store/reducer.js +++ b/editor/store/reducer.js @@ -43,7 +43,8 @@ const MAX_RECENT_BLOCKS = 8; * raw value in place of its original object form. * * @param {*} value Original value - * @return {*} Raw value + * + * @returns {*} Raw value. */ export function getPostRawValue( value ) { if ( value && 'object' === typeof value && 'raw' in value ) { @@ -65,7 +66,8 @@ export function getPostRawValue( value ) { * * @param {Object} state Current state * @param {Object} action Dispatched action - * @return {Object} Updated state + * + * @returns {Object} Updated state. */ export const editor = flow( [ combineReducers, @@ -311,7 +313,8 @@ export const editor = flow( [ * * @param {Object} state Current state * @param {Object} action Dispatched action - * @return {Object} Updated state + * + * @returns {Object} Updated state. */ export function currentPost( state = {}, action ) { switch ( action.type ) { @@ -340,7 +343,8 @@ export function currentPost( state = {}, action ) { * * @param {Boolean} state Current state * @param {Object} action Dispatched action - * @return {Boolean} Updated state + * + * @returns {Boolean} Updated state. */ export function isTyping( state = false, action ) { switch ( action.type ) { @@ -359,7 +363,8 @@ export function isTyping( state = false, action ) { * * @param {Object} state Current state * @param {Object} action Dispatched action - * @return {Object} Updated state + * + * @returns {Object} Updated state. */ export function blockSelection( state = { start: null, @@ -446,7 +451,8 @@ export function blockSelection( state = { * * @param {Object} state Current state * @param {Object} action Dispatched action - * @return {Object} Updated state + * + * @returns {Object} Updated state. */ export function hoveredBlock( state = null, action ) { switch ( action.type ) { @@ -484,7 +490,8 @@ export function blocksMode( state = {}, action ) { * * @param {Object} state Current state * @param {Object} action Dispatched action - * @return {Object} Updated state + * + * @returns {Object} Updated state. */ export function blockInsertionPoint( state = {}, action ) { switch ( action.type ) { @@ -506,7 +513,8 @@ export function blockInsertionPoint( state = {}, action ) { * @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 - * @return {string} Updated state + * + * @returns {string} Updated state. */ export function preferences( state = PREFERENCES_DEFAULTS, action ) { switch ( action.type ) { @@ -590,7 +598,8 @@ export function panel( state = 'document', action ) { * * @param {Object} state Current state * @param {Object} action Dispatched action - * @return {Object} Updated state + * + * @returns {Object} Updated state. */ export function saving( state = {}, action ) { switch ( action.type ) { diff --git a/editor/store/selectors.js b/editor/store/selectors.js index e806ef9dcc06e..f05f794c07da3 100644 --- a/editor/store/selectors.js +++ b/editor/store/selectors.js @@ -32,7 +32,8 @@ const MAX_FREQUENT_BLOCKS = 3; * Returns the current editing mode. * * @param {Object} state Global application state - * @return {String} Editing mode + * + * @returns {String} Editing mode. */ export function getEditorMode( state ) { return getPreference( state, 'mode', 'visual' ); @@ -42,7 +43,8 @@ export function getEditorMode( state ) { * Returns the state of legacy meta boxes. * * @param {Object} state Global application state - * @return {Object} State of meta boxes + * + * @returns {Object} State of meta boxes. */ export function getMetaBoxes( state ) { return state.metaBoxes; @@ -53,7 +55,8 @@ export function getMetaBoxes( state ) { * * @param {Object} state Global application state * @param {String} location Location of the meta box. - * @return {Object} State of meta box at specified location. + * + * @returns {Object} State of meta box at specified location. */ export function getMetaBox( state, location ) { return getMetaBoxes( state )[ location ]; @@ -63,7 +66,8 @@ export function getMetaBox( state, location ) { * Returns a list of dirty meta box locations. * * @param {Object} state Global application state - * @return {Array} Array of locations for dirty meta boxes. + * + * @returns {Array} Array of locations for dirty meta boxes. */ export const getDirtyMetaBoxes = createSelector( ( state ) => { @@ -83,7 +87,8 @@ export const getDirtyMetaBoxes = createSelector( * but a normal area is not dirty, this will overall return dirty. * * @param {Object} state Global application state - * @return {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; @@ -91,7 +96,8 @@ export const isMetaBoxStateDirty = ( state ) => getDirtyMetaBoxes( state ).lengt * Returns the current active panel for the sidebar. * * @param {Object} state Global application state - * @return {String} Active sidebar panel + * + * @returns {String} Active sidebar panel. */ export function getActivePanel( state ) { return state.panel; @@ -101,7 +107,8 @@ export function getActivePanel( state ) { * Returns the preferences (these preferences are persisted locally) * * @param {Object} state Global application state - * @return {Object} Preferences Object + * + * @returns {Object} Preferences Object. */ export function getPreferences( state ) { return state.preferences; @@ -112,7 +119,8 @@ export function getPreferences( state ) { * @param {Object} state Global application state * @param {String} preferenceKey Preference Key * @param {Mixed} defaultValue Default Value - * @return {Mixed} Preference Value + * + * @returns {Mixed} Preference Value. */ export function getPreference( state, preferenceKey, defaultValue ) { const preferences = getPreferences( state ); @@ -125,7 +133,8 @@ export function getPreference( state, preferenceKey, defaultValue ) { * * @param {Object} state Global application state * @param {string} sidebar Sidebar name (leave undefined for the default sidebar) - * @return {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' ); @@ -140,7 +149,8 @@ export function isSidebarOpened( state, sidebar ) { * Returns true if there's any open sidebar (mobile, desktop or publish) * * @param {Object} state Global application state - * @return {Boolean} Whether sidebar is open + * + * @returns {Boolean} Whether sidebar is open. */ export function hasOpenSidebar( state ) { const sidebars = getPreference( state, 'sidebars' ); @@ -154,7 +164,8 @@ export function hasOpenSidebar( state ) { * * @param {Object} state Global application state * @param {STring} panel Sidebar panel name - * @return {Boolean} Whether sidebar is open + * + * @returns {Boolean} Whether sidebar is open. */ export function isEditorSidebarPanelOpened( state, panel ) { const panels = getPreference( state, 'panels' ); @@ -165,7 +176,8 @@ export function isEditorSidebarPanelOpened( state, panel ) { * Returns true if any past editor history snapshots exist, or false otherwise. * * @param {Object} state Global application state - * @return {Boolean} Whether undo history exists + * + * @returns {Boolean} Whether undo history exists. */ export function hasEditorUndo( state ) { return state.editor.past.length > 0; @@ -176,7 +188,8 @@ export function hasEditorUndo( state ) { * otherwise. * * @param {Object} state Global application state - * @return {Boolean} Whether redo history exists + * + * @returns {Boolean} Whether redo history exists. */ export function hasEditorRedo( state ) { return state.editor.future.length > 0; @@ -187,7 +200,8 @@ export function hasEditorRedo( state ) { * the post has been saved. * * @param {Object} state Global application state - * @return {Boolean} Whether the post is new + * + * @returns {Boolean} Whether the post is new. */ export function isEditedPostNew( state ) { return getCurrentPost( state ).status === 'auto-draft'; @@ -198,7 +212,8 @@ export function isEditedPostNew( state ) { * false if the editing state matches the saved or new post. * * @param {Object} state Global application state - * @return {Boolean} Whether unsaved values exist + * + * @returns {Boolean} Whether unsaved values exist. */ export function isEditedPostDirty( state ) { return state.editor.isDirty || isMetaBoxStateDirty( state ); @@ -209,7 +224,8 @@ export function isEditedPostDirty( state ) { * the currently edited post is new (and has never been saved before). * * @param {Object} state Global application state - * @return {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 ); @@ -219,7 +235,9 @@ export function isCleanNewPost( state ) { * Returns true if the current window size corresponds to mobile resolutions (<= medium breakpoint) * * @param {Object} state Global application state - * @return {Boolean} Whether current window size corresponds to mobile resolutions + * + * @returns {Boolean} Whether current window size corresponds to + * mobile resolutions. */ export function isMobile( state ) { return state.mobile; @@ -231,7 +249,8 @@ export function isMobile( state ) { * values if the post has not yet been saved. * * @param {Object} state Global application state - * @return {Object} Post object + * + * @returns {Object} Post object. */ export function getCurrentPost( state ) { return state.currentPost; @@ -241,7 +260,8 @@ export function getCurrentPost( state ) { * Returns the post type of the post currently being edited * * @param {Object} state Global application state - * @return {String} Post type + * + * @returns {String} Post type. */ export function getCurrentPostType( state ) { return state.currentPost.type; @@ -252,7 +272,8 @@ export function getCurrentPostType( state ) { * not yet been saved. * * @param {Object} state Global application state - * @return {?Number} ID of current post + * + * @returns {?Number} ID of current post. */ export function getCurrentPostId( state ) { return getCurrentPost( state ).id || null; @@ -262,7 +283,8 @@ export function getCurrentPostId( state ) { * Returns the number of revisions of the post currently being edited. * * @param {Object} state Global application state - * @return {Number} Number of revisions + * + * @returns {Number} Number of revisions. */ export function getCurrentPostRevisionsCount( state ) { return get( getCurrentPost( state ), 'revisions.count', 0 ); @@ -273,7 +295,8 @@ export function getCurrentPostRevisionsCount( state ) { * or null if the post has no revisions. * * @param {Object} state Global application state - * @return {?Number} ID of the last revision + * + * @returns {?Number} ID of the last revision. */ export function getCurrentPostLastRevisionId( state ) { return get( getCurrentPost( state ), 'revisions.last_id', null ); @@ -284,7 +307,8 @@ export function getCurrentPostLastRevisionId( state ) { * been saved. * * @param {Object} state Global application state - * @return {Object} Object of key value pairs comprising unsaved edits + * + * @returns {Object} Object of key value pairs comprising unsaved edits. */ export function getPostEdits( state ) { return state.editor.present.edits; @@ -297,7 +321,8 @@ export function getPostEdits( state ) { * * @param {Object} state Global application state * @param {String} attributeName Post attribute name - * @return {*} Post attribute value + * + * @returns {*} Post attribute value. */ export function getEditedPostAttribute( state, attributeName ) { return state.editor.present.edits[ attributeName ] === undefined ? @@ -311,7 +336,8 @@ export function getEditedPostAttribute( state, attributeName ) { * "private", "password", or "public". * * @param {Object} state Global application state - * @return {String} Post visibility + * + * @returns {String} Post visibility. */ export function getEditedPostVisibility( state ) { const status = getEditedPostAttribute( state, 'status' ); @@ -329,7 +355,8 @@ export function getEditedPostVisibility( state ) { * Return true if the current post has already been published. * * @param {Object} state Global application state - * @return {Boolean} Whether the post has been published + * + * @returns {Boolean} Whether the post has been published. */ export function isCurrentPostPublished( state ) { const post = getCurrentPost( state ); @@ -342,7 +369,8 @@ export function isCurrentPostPublished( state ) { * Return true if the post being edited can be published * * @param {Object} state Global application state - * @return {Boolean} Whether the post can been published + * + * @returns {Boolean} Whether the post can been published. */ export function isEditedPostPublishable( state ) { const post = getCurrentPost( state ); @@ -354,7 +382,8 @@ export function isEditedPostPublishable( state ) { * contain a title, an excerpt, or non-empty content to be valid for save. * * @param {Object} state Global application state - * @return {Boolean} Whether the post can be saved + * + * @returns {Boolean} Whether the post can be saved. */ export function isEditedPostSaveable( state ) { return ( @@ -369,7 +398,8 @@ export function isEditedPostSaveable( state ) { * unsaved status values. * * @param {Object} state Global application state - * @return {Boolean} Whether the post has been published + * + * @returns {Boolean} Whether the post has been published. */ export function isEditedPostBeingScheduled( state ) { const date = getEditedPostAttribute( state, 'date' ); @@ -384,7 +414,8 @@ export function isEditedPostBeingScheduled( state ) { * if different than the saved post. * * @param {Object} state Global application state - * @return {String} Raw post title + * + * @returns {String} Raw post title. */ export function getEditedPostTitle( state ) { const editedTitle = getPostEdits( state ).title; @@ -402,7 +433,8 @@ export function getEditedPostTitle( state ) { * Gets the document title to be used. * * @param {Object} state Global application state - * @return {string} Document title + * + * @returns {string} Document title. */ export function getDocumentTitle( state ) { let title = getEditedPostTitle( state ); @@ -418,7 +450,8 @@ export function getDocumentTitle( state ) { * value if different than the saved post. * * @param {Object} state Global application state - * @return {String} Raw post excerpt + * + * @returns {String} Raw post excerpt. */ export function getEditedPostExcerpt( state ) { return state.editor.present.edits.excerpt === undefined ? @@ -430,7 +463,8 @@ export function getEditedPostExcerpt( state ) { * Returns a URL to preview the post being edited. * * @param {Object} state Global application state - * @return {String} Preview URL + * + * @returns {String} Preview URL. */ export function getEditedPostPreviewLink( state ) { const link = state.currentPost.link; @@ -449,7 +483,8 @@ export function getEditedPostPreviewLink( state ) { * * @param {Object} state Global application state * @param {String} uid Block unique ID - * @return {Object} Parsed block object + * + * @returns {Object} Parsed block object. */ export const getBlock = createSelector( ( state, uid ) => { @@ -502,7 +537,8 @@ function getPostMeta( state, key ) { * Note: It's important to memoize this selector to avoid return a new instance on each call * * @param {Object} state Global application state - * @return {Object[]} Post blocks + * + * @returns {Object[]} Post blocks. */ export const getBlocks = createSelector( ( state ) => { @@ -518,7 +554,8 @@ export const getBlocks = createSelector( * Returns the number of blocks currently present in the post. * * @param {Object} state Global application state - * @return {Number} Number of blocks in the post + * + * @returns {Number} Number of blocks in the post. */ export function getBlockCount( state ) { return getBlockUids( state ).length; @@ -528,7 +565,8 @@ export function getBlockCount( state ) { * Returns the number of blocks currently selected in the post. * * @param {Object} state Global application state - * @return {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; @@ -544,7 +582,8 @@ export function getSelectedBlockCount( state ) { * Returns the currently selected block, or null if there is no selected block. * * @param {Object} state Global application state - * @return {?Object} Selected block + * + * @returns {?Object} Selected block. */ export function getSelectedBlock( state ) { const { start, end } = state.blockSelection; @@ -560,7 +599,8 @@ export function getSelectedBlock( state ) { * array if there is no multi-selection. * * @param {Object} state Global application state - * @return {Array} Multi-selected block unique UDs + * + * @returns {Array} Multi-selected block unique IDs. */ export const getMultiSelectedBlockUids = createSelector( ( state ) => { @@ -591,7 +631,8 @@ export const getMultiSelectedBlockUids = createSelector( * there is no multi-selection. * * @param {Object} state Global application state - * @return {Array} Multi-selected block objects + * + * @returns {Array} Multi-selected block objects. */ export const getMultiSelectedBlocks = createSelector( ( state ) => getMultiSelectedBlockUids( state ).map( ( uid ) => getBlock( state, uid ) ), @@ -610,7 +651,8 @@ export const getMultiSelectedBlocks = createSelector( * if there is no multi-selection. * * @param {Object} state Global application state - * @return {?String} First unique block ID in the multi-selection set + * + * @returns {?String} First unique block ID in the multi-selection set. */ export function getFirstMultiSelectedBlockUid( state ) { return first( getMultiSelectedBlockUids( state ) ) || null; @@ -621,7 +663,8 @@ export function getFirstMultiSelectedBlockUid( state ) { * if there is no multi-selection. * * @param {Object} state Global application state - * @return {?String} Last unique block ID in the multi-selection set + * + * @returns {?String} Last unique block ID in the multi-selection set. */ export function getLastMultiSelectedBlockUid( state ) { return last( getMultiSelectedBlockUids( state ) ) || null; @@ -634,7 +677,8 @@ export function getLastMultiSelectedBlockUid( state ) { * * @param {Object} state Global application state * @param {String} uid Block unique ID - * @return {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; @@ -646,7 +690,8 @@ export function isFirstMultiSelectedBlock( state, uid ) { * * @param {Object} state Global application state * @param {String} uid Block unique ID - * @return {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; @@ -660,7 +705,8 @@ export function isBlockMultiSelected( state, uid ) { * getFirstMultiSelectedBlockUid(). * * @param {Object} state Global application state - * @return {?String} Unique ID of block beginning multi-selection + * + * @returns {?String} Unique ID of block beginning multi-selection. */ export function getMultiSelectedBlocksStartUid( state ) { const { start, end } = state.blockSelection; @@ -678,7 +724,8 @@ export function getMultiSelectedBlocksStartUid( state ) { * getLastMultiSelectedBlockUid(). * * @param {Object} state Global application state - * @return {?String} Unique ID of block ending multi-selection + * + * @returns {?String} Unique ID of block ending multi-selection. */ export function getMultiSelectedBlocksEndUid( state ) { const { start, end } = state.blockSelection; @@ -693,7 +740,8 @@ export function getMultiSelectedBlocksEndUid( state ) { * in the order they appear in the post. * * @param {Object} state Global application state - * @return {Array} Ordered unique IDs of post blocks + * + * @returns {Array} Ordered unique IDs of post blocks. */ export function getBlockUids( state ) { return state.editor.present.blockOrder; @@ -705,7 +753,8 @@ export function getBlockUids( state ) { * * @param {Object} state Global application state * @param {String} uid Block unique ID - * @return {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 ); @@ -717,7 +766,8 @@ export function getBlockIndex( state, uid ) { * * @param {Object} state Global application state * @param {String} uid Block unique ID - * @return {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; @@ -729,7 +779,8 @@ export function isFirstBlock( state, uid ) { * * @param {Object} state Global application state * @param {String} uid Block unique ID - * @return {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; @@ -741,7 +792,8 @@ export function isLastBlock( state, uid ) { * * @param {Object} state Global application state * @param {String} uid Block unique ID - * @return {Object} Block occurring before specified unique ID + * + * @returns {Object} Block occurring before specified unique ID. */ export function getPreviousBlock( state, uid ) { const order = getBlockIndex( state, uid ); @@ -754,7 +806,8 @@ export function getPreviousBlock( state, uid ) { * * @param {Object} state Global application state * @param {String} uid Block unique ID - * @return {Object} Block occurring after specified unique ID + * + * @returns {Object} Block occurring after specified unique ID. */ export function getNextBlock( state, uid ) { const order = getBlockIndex( state, uid ); @@ -767,7 +820,8 @@ export function getNextBlock( state, uid ) { * * @param {Object} state Global application state * @param {String} uid Block unique ID - * @return {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; @@ -787,7 +841,9 @@ export function isBlockSelected( state, uid ) { * * @param {Object} state Global application state * @param {String} uid Block unique ID - * @return {Boolean} Whether block is selected and not the last in the selection + * + * @returns {Boolean} Whether block is selected and not the last in + * the selection. */ export function isBlockWithinSelection( state, uid ) { if ( ! uid ) { @@ -805,7 +861,8 @@ export function isBlockWithinSelection( state, uid ) { * * @param {Object} state Global application state * @param {String} uid Block unique ID - * @return {Boolean} Whether block is hovered + * + * @returns {Boolean} Whether block is hovered. */ export function isBlockHovered( state, uid ) { return state.hoveredBlock === uid; @@ -818,7 +875,8 @@ export function isBlockHovered( state, uid ) { * * @param {Object} state Global application state * @param {String} uid Block unique ID - * @return {Object} Block focus state + * + * @returns {Object} Block focus state. */ export function getBlockFocus( state, uid ) { // If there is multi-selection, keep returning the focus object for the start block. @@ -833,7 +891,8 @@ export function getBlockFocus( state, uid ) { * Whether in the process of multi-selecting or not. * * @param {Object} state Global application state - * @return {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; @@ -843,7 +902,8 @@ export function isMultiSelecting( state ) { * Whether is selection disable or not. * * @param {Object} state Global application state - * @return {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; @@ -854,7 +914,8 @@ export function isSelectionEnabled( state ) { * * @param {Object} state Global application state * @param {String} uid Block unique ID - * @return {Object} Block editing mode + * + * @returns {Object} Block editing mode. */ export function getBlockMode( state, uid ) { return state.blocksMode[ uid ] || 'visual'; @@ -864,7 +925,8 @@ export function getBlockMode( state, uid ) { * Returns true if the user is typing, or false otherwise. * * @param {Object} state Global application state - * @return {Boolean} Whether user is typing + * + * @returns {Boolean} Whether user is typing. */ export function isTyping( state ) { return state.isTyping; @@ -875,7 +937,8 @@ export function isTyping( state ) { * be placed. Defaults to the last position * * @param {Object} state Global application state - * @return {?String} Unique ID after which insertion will occur + * + * @returns {?String} Unique ID after which insertion will occur. */ export function getBlockInsertionPoint( state ) { if ( getEditorMode( state ) !== 'visual' ) { @@ -905,7 +968,8 @@ export function getBlockInsertionPoint( state ) { * sibling block, or null if the inserter is not actively visible. * * @param {Object} state Global application state - * @return {?Number} Whether the inserter is currently visible + * + * @returns {?Number} Whether the inserter is currently visible. */ export function getBlockSiblingInserterPosition( state ) { const { position } = state.blockInsertionPoint; @@ -920,7 +984,8 @@ export function getBlockSiblingInserterPosition( state ) { * Returns true if we should show the block insertion point * * @param {Object} state Global application state - * @return {?Boolean} Whether the insertion point is visible or not + * + * @returns {?Boolean} Whether the insertion point is visible or not. */ export function isBlockInsertionPointVisible( state ) { return !! state.blockInsertionPoint.visible; @@ -930,7 +995,8 @@ export function isBlockInsertionPointVisible( state ) { * Returns true if the post is currently being saved, or false otherwise. * * @param {Object} state Global application state - * @return {Boolean} Whether post is being saved + * + * @returns {Boolean} Whether post is being saved. */ export function isSavingPost( state ) { return state.saving.requesting; @@ -941,7 +1007,8 @@ export function isSavingPost( state ) { * otherwise. * * @param {Object} state Global application state - * @return {Boolean} Whether the post was saved successfully + * + * @returns {Boolean} Whether the post was saved successfully. */ export function didPostSaveRequestSucceed( state ) { return state.saving.successful; @@ -952,7 +1019,8 @@ export function didPostSaveRequestSucceed( state ) { * otherwise. * * @param {Object} state Global application state - * @return {Boolean} Whether the post save failed + * + * @returns {Boolean} Whether the post save failed. */ export function didPostSaveRequestFail( state ) { return !! state.saving.error; @@ -964,7 +1032,8 @@ export function didPostSaveRequestFail( state ) { * default post format. Returns null if the format cannot be determined. * * @param {Object} state Global application state - * @return {?String} Suggested post format + * + * @returns {?String} Suggested post format. */ export function getSuggestedPostFormat( state ) { const blocks = state.editor.present.blockOrder; @@ -1011,7 +1080,8 @@ export function getSuggestedPostFormat( state ) { * before falling back to serialization of block state. * * @param {Object} state Global application state - * @return {String} Post content + * + * @returns {String} Post content. */ export const getEditedPostContent = createSelector( ( state ) => { @@ -1033,7 +1103,8 @@ export const getEditedPostContent = createSelector( * Returns the user notices array * * @param {Object} state Global application state - * @return {Array} List of notices + * + * @returns {Array} List of notices. */ export function getNotices( state ) { return state.notices; @@ -1043,7 +1114,8 @@ export function getNotices( state ) { * Resolves the list of recently used block names into a list of block type settings. * * @param {Object} state Global application state - * @return {Array} List of recently used blocks + * + * @returns {Array} List of recently used blocks. */ export function getRecentlyUsedBlocks( state ) { // resolves the block names in the state to the block type settings @@ -1056,7 +1128,8 @@ export function getRecentlyUsedBlocks( state ) { * in the inserter. * * @param {Object} state Global application state - * @return {Array} List of block type settings + * + * @returns {Array} List of block type settings. */ export const getMostFrequentlyUsedBlocks = createSelector( ( state ) => { @@ -1075,7 +1148,8 @@ export const getMostFrequentlyUsedBlocks = createSelector( * Returns whether the toolbar should be fixed or not. * * @param {Object} state Global application state. - * @return {Boolean} True if toolbar is fixed. + * + * @returns {Boolean} True if toolbar is fixed. */ export function hasFixedToolbar( state ) { return ! isMobile( state ) && isFeatureActive( state, 'fixedToolbar' ); @@ -1086,7 +1160,8 @@ export function hasFixedToolbar( state ) { * * @param {Object} state Global application state * @param {String} feature Feature slug - * @return {Booleean} Is active + * + * @returns {Booleean} Is active. */ export function isFeatureActive( state, feature ) { return !! state.preferences.features[ feature ]; @@ -1097,7 +1172,8 @@ export function isFeatureActive( state, feature ) { * * @param {Object} state Global application state * @param {String} ref The reusable block's ID - * @return {Object} The reusable block, or null if none exists + * + * @returns {Object} The reusable block, or null if none exists. */ export function getReusableBlock( state, ref ) { return state.reusableBlocks.data[ ref ] || null; @@ -1108,7 +1184,8 @@ export function getReusableBlock( state, ref ) { * * @param {*} state Global application state * @param {*} ref The reusable block's ID - * @return {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; @@ -1118,7 +1195,8 @@ export function isSavingReusableBlock( state, ref ) { * Returns an array of all reusable blocks. * * @param {Object} state Global application state - * @return {Array} An array of all reusable blocks. + * + * @returns {Array} An array of all reusable blocks. */ export function getReusableBlocks( state ) { return Object.values( state.reusableBlocks.data ); @@ -1130,7 +1208,8 @@ export function getReusableBlocks( state ) { * * @param {Object} state Current global application state * @param {Object} transactionId Optimist transaction ID - * @return {Object} Global application state prior to transaction + * + * @returns {Object} Global application state prior to transaction. */ export function getStateBeforeOptimisticTransaction( state, transactionId ) { const transaction = find( state.optimist, ( entry ) => ( @@ -1145,7 +1224,8 @@ export function getStateBeforeOptimisticTransaction( state, transactionId ) { * Returns true if the post is being published, or false otherwise * * @param {Object} state Global application state - * @return {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 cfd2df829a051..4da3da41e4092 100644 --- a/editor/utils/dom.js +++ b/editor/utils/dom.js @@ -15,7 +15,8 @@ const { TEXT_NODE } = window.Node; * @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 - * @return {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 ) ) { @@ -80,7 +81,8 @@ export function isHorizontalEdge( container, isReverse, collapseRanges = false ) * @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 - * @return {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 ) ) { @@ -201,7 +203,8 @@ export function placeCaretAtHorizontalEdge( container, isReverse ) { * @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. - * @return {?Range} The best range for the given point. + * + * @returns {?Range} The best range for the given point. */ function caretRangeFromPoint( doc, x, y ) { if ( doc.caretRangeFromPoint ) { @@ -230,7 +233,8 @@ function caretRangeFromPoint( doc, x, y ) { * @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. - * @return {?Range} The best range for the given point. + * + * @returns {?Range} The best range for the given point. */ function hiddenCaretRangeFromPoint( doc, x, y, container ) { container.style.zIndex = '10000'; @@ -310,7 +314,8 @@ export function placeCaretAtVerticalEdge( container, isReverse, rect, mayUseScro * Check whether the given node in an input field. * * @param {HTMLElement} element The HTML element. - * @return {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 ( diff --git a/editor/utils/mobile/index.js b/editor/utils/mobile/index.js index ed3dedfa355b7..697d73599210a 100644 --- a/editor/utils/mobile/index.js +++ b/editor/utils/mobile/index.js @@ -8,7 +8,8 @@ import { toggleSidebar } from '../../store/actions'; * Disables isSidebarOpened on rehydrate payload if the user is on a mobile screen size. * * @param {Object} payload rehydrate payload - * @return {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 b0ce027abae8e..735d0bef6c612 100644 --- a/editor/utils/url.js +++ b/editor/utils/url.js @@ -8,7 +8,7 @@ import { addQueryArgs } from '@wordpress/url'; * * @param {Number} postId Post ID * - * @return {String} URL + * @returns {String} Post edit URL. */ export function getPostEditUrl( postId ) { return getWPAdminURL( 'post.php', { post: postId, action: 'edit' } ); @@ -20,7 +20,7 @@ export function getPostEditUrl( postId ) { * @param {String} page page to navigate to * @param {Object} query Query Args * - * @return {String} URL + * @returns {String} WPAdmin URL. */ export function getWPAdminURL( page, query ) { return addQueryArgs( page, query ); @@ -31,7 +31,7 @@ export function getWPAdminURL( page, query ) { * * @param {String} url Original url * - * @return {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 7ed34b586b605..557b11fa55808 100644 --- a/editor/utils/with-change-detection/index.js +++ b/editor/utils/with-change-detection/index.js @@ -11,7 +11,8 @@ import { includes } from 'lodash'; * @param {Function} reducer Original reducer * @param {?Object} options Optional options * @param {?Array} options.resetTypes Action types upon which to reset dirty - * @return {Function} Enhanced reducer + * + * @returns {Function} Enhanced reducer. */ export default function withChangeDetection( reducer, options = {} ) { return ( state, action ) => { diff --git a/editor/utils/with-history/index.js b/editor/utils/with-history/index.js index 7fa250d1319e7..a01d9b3953f35 100644 --- a/editor/utils/with-history/index.js +++ b/editor/utils/with-history/index.js @@ -10,7 +10,8 @@ import { includes } from 'lodash'; * @param {Function} reducer Original reducer * @param {?Object} options Optional options * @param {?Array} options.resetTypes Action types upon which to clear past - * @return {Function} Enhanced reducer + * + * @returns {Function} Enhanced reducer. */ export default function withHistory( reducer, options = {} ) { const initialState = { diff --git a/element/index.js b/element/index.js index f850aa80b7955..33968682dd3e9 100644 --- a/element/index.js +++ b/element/index.js @@ -15,7 +15,8 @@ import { camelCase, flowRight, isString, upperFirst } from 'lodash'; * set to apply to DOM node or values to * pass through to element creator * @param {...WPElement} children Descendant elements - * @return {WPElement} Element + * + * @returns {WPElement} Element. */ export { createElement }; @@ -44,7 +45,8 @@ export { Component }; * * @param {WPElement} element Element * @param {?Object} props Props to apply to cloned element - * @return {WPElement} Cloned element + * + * @returns {WPElement} Cloned element. */ export { cloneElement }; @@ -77,7 +79,8 @@ export { createPortal }; * Renders a given element into a string * * @param {WPElement} element Element to render - * @return {String} HTML + * + * @returns {String} HTML. */ export { renderToStaticMarkup as renderToString }; @@ -85,7 +88,8 @@ export { renderToStaticMarkup as renderToString }; * Concatenate two or more React children objects * * @param {...?Object} childrenArguments Array of children arguments (array of arrays/strings/objects) to concatenate - * @return {Array} The concatenated value + * + * @returns {Array} The concatenated value. */ export function concatChildren( ...childrenArguments ) { return childrenArguments.reduce( ( memo, children, i ) => { @@ -108,7 +112,8 @@ export function concatChildren( ...childrenArguments ) { * * @param {?Object} children Children object * @param {String} nodeName Node name - * @return {?Object} The updated children object + * + * @returns {?Object} The updated children object. */ export function switchChildrenNodeName( children, nodeName ) { return children && Children.map( children, ( elt, index ) => { @@ -125,7 +130,8 @@ export function switchChildrenNodeName( children, nodeName ) { * composition, where each successive invocation is supplied the return value of the previous. * * @param {...Function} hocs The HOC functions to invoke. - * @return {Function} Returns the new composite function. + * + * @returns {Function} Returns the new composite function. */ export { flowRight as compose }; @@ -135,7 +141,8 @@ export { flowRight as compose }; * * @param {Function|Component} BaseComponent used to detect the existing display name. * @param {String} wrapperName Wrapper name to prepend to the display name. - * @return {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 90d78a92cafa8..7d814f1ca65d0 100644 --- a/i18n/babel-plugin.js +++ b/i18n/babel-plugin.js @@ -87,7 +87,8 @@ const REGEXP_TRANSLATOR_COMMENT = /^\s*translators:\s*([\s\S]+)/im; * represenation of that node's value. * * @param {Object} node AST node - * @return {String} String value + * + * @returns {String} String value. */ function getNodeAsString( node ) { switch ( node.type ) { @@ -111,7 +112,8 @@ function getNodeAsString( node ) { * @param {Object} path Traversal path * @param {Number} _originalNodeLine Private: In recursion, line number of * the original node passed - * @return {?string} Translator comment + * + * @returns {?string} Translator comment. */ function getTranslatorComment( path, _originalNodeLine ) { const { node, parent, parentPath } = path; @@ -159,7 +161,8 @@ function getTranslatorComment( path, _originalNodeLine ) { * the translation object. * * @param {string} key Key to test - * @return {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 ); @@ -171,7 +174,8 @@ function isValidTranslationKey( key ) { * * @param {Object} a First translation object * @param {Object} b Second translation object - * @return {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 f61c35fa7c650..c58abb308caf2 100644 --- a/i18n/index.js +++ b/i18n/index.js @@ -20,7 +20,7 @@ export function setLocaleData( data ) { * Returns the current Jed instance, initializing with a default configuration * if not already assigned. * - * @return {Jed} Jed instance + * @returns {Jed} Jed instance. */ export function getI18n() { if ( ! i18n ) { @@ -36,7 +36,8 @@ export function getI18n() { * @see https://developer.wordpress.org/reference/functions/__/ * * @param {string} text Text to translate - * @return {string} Translated text + * + * @returns {string} Translated text. */ export function __( text ) { return getI18n().gettext( text ); @@ -49,7 +50,8 @@ export function __( text ) { * * @param {string} text Text to translate * @param {string} context Context information for the translators - * @return {string} Translated context string without pipe + * + * @returns {string} Translated context string without pipe. */ export function _x( text, context ) { return getI18n().pgettext( context, text ); @@ -65,7 +67,8 @@ export function _x( text, context ) { * @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 - * @return {string} The translated singular or plural form + * + * @returns {string} The translated singular or plural form. */ export function _n( single, plural, number ) { return getI18n().ngettext( single, plural, number ); @@ -82,7 +85,8 @@ export function _n( single, plural, number ) { * @param {Number} number The number to compare against to use either the * singular or plural form * @param {string} context Context information for the translators - * @return {string} The translated singular or plural form + * + * @returns {string} The translated singular or plural form. */ export function _nx( single, plural, number, context ) { return getI18n().npgettext( context, single, plural, number ); diff --git a/utils/focus/focusable.js b/utils/focus/focusable.js index 58e29c58d968d..924f3f0c2003d 100644 --- a/utils/focus/focusable.js +++ b/utils/focus/focusable.js @@ -41,7 +41,8 @@ const SELECTOR = [ * nor visibility: hidden). * * @param {Element} element DOM element to test - * @return {Boolean} Whether element is visible + * + * @returns {Boolean} Whether element is visible. */ function isVisible( element ) { return ( @@ -57,7 +58,8 @@ function isVisible( element ) { * referenced by an image somewhere in the document. * * @param {Element} element DOM area element to test - * @return {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]' ); @@ -73,7 +75,8 @@ function isValidFocusableArea( element ) { * Returns all focusable elements within a given context. * * @param {Element} context Element in which to search - * @return {Element[]} Focusable elements + * + * @returns {Element[]} Focusable elements. */ export function find( context ) { const elements = context.querySelectorAll( SELECTOR ); diff --git a/utils/focus/tabbable.js b/utils/focus/tabbable.js index 193f397d8df4f..be18332b2830a 100644 --- a/utils/focus/tabbable.js +++ b/utils/focus/tabbable.js @@ -12,7 +12,8 @@ import { find as findFocusable } from './focusable'; * @see https://bugzilla.mozilla.org/show_bug.cgi?id=1190261 * * @param {Element} element Element from which to retrieve - * @return {?Number} Tab index of element (default 0) + * + * @returns {?Number} Tab index of element (default 0). */ function getTabIndex( element ) { const tabIndex = element.getAttribute( 'tabindex' ); @@ -23,7 +24,8 @@ function getTabIndex( element ) { * Returns true if the specified element is tabbable, or false otherwise. * * @param {Element} element Element to test - * @return {Boolean} Whether element is tabbable + * + * @returns {Boolean} Whether element is tabbable. */ function isTabbableIndex( element ) { return getTabIndex( element ) !== -1; @@ -37,7 +39,8 @@ function isTabbableIndex( element ) { * * @param {Element} element Element * @param {Number} index Array index of element - * @return {Object} Mapped object with element, index + * + * @returns {Object} Mapped object with element, index. */ function mapElementToObjectTabbable( element, index ) { return { element, index }; @@ -48,7 +51,8 @@ function mapElementToObjectTabbable( element, index ) { * element value. * * @param {Object} object Mapped object with index - * @return {Element} Mapped object element + * + * @returns {Element} Mapped object element. */ function mapObjectTabbableToElement( object ) { return object.element; @@ -61,7 +65,8 @@ function mapObjectTabbableToElement( object ) { * * @param {Object} a First object to compare * @param {Object} b Second object to compare - * @return {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 c1ef419c7def2..f7f2ef5ae8c58 100644 --- a/utils/focus/test/utils/create-element.js +++ b/utils/focus/test/utils/create-element.js @@ -3,7 +3,8 @@ * since JSDOM does have its own internal layout engine. * * @param {String} type Element type - * @return {HTMLElement} Layout-emulated element + * + * @returns {HTMLElement} Layout-emulated element. */ export default function createElement( type ) { const element = document.createElement( type ); diff --git a/utils/mediaupload.js b/utils/mediaupload.js index 17b45febdf308..21223c5ee32f0 100644 --- a/utils/mediaupload.js +++ b/utils/mediaupload.js @@ -47,7 +47,8 @@ export function mediaUpload( filesList, onImagesChange ) { /** * @param {File} file Media File to Save - * @return {Promise} Media Object Promise + * + * @returns {Promise} Media Object Promise. */ export function createMediaFromFile( file ) { // Create upload payload diff --git a/utils/terms.js b/utils/terms.js index f58531742c456..98253862be816 100644 --- a/utils/terms.js +++ b/utils/terms.js @@ -7,7 +7,8 @@ import { groupBy } from 'lodash'; * Returns terms in a tree form ª * @param {Array} flatTerms Array of terms in flat format. - * @return {Array} Array of terms in tree format. + * + * @returns {Array} Array of terms in tree format. */ export function buildTermsTree( flatTerms ) { const termsByParent = groupBy( flatTerms, 'parent' );