docs: use @returns over @return JSDoc tag (#4464)

Fixes per WordPress JavaScript Inline Coding Standards:

• Use `@returns` over `@return` JSDoc tag fixing ESLint `jsdoc/check-tag-names` "Invalid JSDoc tag" warnings
• Ensures there is a blank new line before the `@returns` JSDoc tag
• Ensures the `@returns` JSDoc tag description ends with a period.

See https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/

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;

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 {

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 ) => {

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.

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( '' );

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';

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<String,*>} allAttributes Attributes from in-memory block data
  * @param   {Object<String,*>} blockType     Block type
- * @returns {Object<String,*>}               Subset of attributes for comment serialization
+ *
+ * @returns {Object<String,*>} 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' );