Merge pull request #4563 from WordPress/update/eslint-jsdoc

JSDoc fixes

Author: ntwb

blocks/api/categories.js

@@ -21,7 +21,7 @@ const categories = [
 ];
 
 /**
- * Returns all the block categories
+ * Returns all the block categories.
  *
  * @returns {Array} Block categories.
  */

blocks/api/factory.js

@@ -30,8 +30,8 @@ import { getBlockType, getBlockTypes } from './registration';
 /**
  * Returns a block object given its type and attributes.
  *
- * @param  {String} name             Block name
- * @param  {Object} blockAttributes  Block attributes
+ * @param {string} name            Block name.
+ * @param {Object} blockAttributes Block attributes.
  *
  * @returns {Object} Block object.
  */
@@ -63,11 +63,12 @@ export function createBlock( name, blockAttributes = {} ) {
 }
 
 /**
- * Returns a predicate that receives a transformation and returns true if the given
- * transformation is able to execute in the situation specified in the params
+ * Returns a predicate that receives a transformation and returns true if the
+ * given transformation is able to execute in the situation specified in the
+ * params.
  *
- * @param  {String}    sourceName    Block name
- * @param  {Boolean}   isMultiBlock  Array of possible block transformations
+ * @param {string}  sourceName   Block name.
+ * @param {boolean} isMultiBlock Array of possible block transformations.
  *
  * @returns {Function} Predicate that receives a block type.
  */
@@ -78,11 +79,12 @@ const isTransformForBlockSource = ( sourceName, isMultiBlock = false ) => ( tran
 );
 
 /**
- * Returns a predicate that receives a block type and returns true if the given block type contains a
- * transformation able to execute in the situation specified in the params
+ * Returns a predicate that receives a block type and returns true if the given
+ * block type contains a transformation able to execute in the situation
+ * specified in the params.
  *
- * @param  {String}    sourceName    Block name
- * @param  {Boolean}   isMultiBlock  Array of possible block transformations
+ * @param {string}  sourceName   Block name.
+ * @param {boolean} isMultiBlock Array of possible block transformations.
  *
  * @returns {Function} Predicate that receives a block type.
  */
@@ -94,9 +96,10 @@ const createIsTypeTransformableFrom = ( sourceName, isMultiBlock = false ) => (
 );
 
 /**
- * Returns an array of possible block transformations that could happen on the set of blocks received as argument.
+ * Returns an array of possible block transformations that could happen on the
+ * set of blocks received as argument.
  *
- * @param  {Array}  blocks Blocks array
+ * @param {Array} blocks Blocks array.
  *
  * @returns {Array} Array of possible block transformations.
  */
@@ -143,8 +146,8 @@ export function getPossibleBlockTransformations( blocks ) {
 /**
  * Switch one or more blocks into one or more blocks of the new block type.
  *
- * @param  {Array|Object}  blocks     Blocks array or block object
- * @param  {string}        name       Block name
+ * @param {Array|Object} blocks Blocks array or block object.
+ * @param {string}       name   Block name.
  *
  * @returns {Array} Array of blocks.
  */
@@ -221,8 +224,10 @@ export function switchToBlockType( blocks, name ) {
 /**
  * Creates a new reusable block.
  *
- * @param {String} type       The type of the block referenced by the reusable block
- * @param {Object} attributes The attributes of the block referenced by the reusable block
+ * @param {string} type       The type of the block referenced by the reusable
+ *                            block.
+ * @param {Object} attributes The attributes of the block referenced by the
+ *                            reusable block.
  *
  * @returns {Object} A reusable block object.
  */

blocks/api/parser.js

@@ -15,12 +15,12 @@ import { getCommentDelimitedContent } from './serializer';
 import { attr, prop, html, text, query, node, children } from './matchers';
 
 /**
- * Returns value coerced to the specified JSON schema type string
+ * Returns value coerced to the specified JSON schema type string.
  *
  * @see http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.25
  *
- * @param  {*}      value Original value
- * @param  {String} type  Type to coerce
+ * @param {*}      value Original value.
+ * @param {string} type  Type to coerce.
  *
  * @returns {*} Coerced value.
  */
@@ -54,11 +54,11 @@ export function asType( value, type ) {
 }
 
 /**
- * Returns an hpq matcher given a source object
+ * Returns an hpq matcher given a source object.
  *
- * @param  {Object}   sourceConfig Attribute Source object
+ * @param {Object} sourceConfig Attribute Source object.
  *
- * @returns {Function} hpq Matcher.
+ * @returns {Function} A hpq Matcher.
  */
 export function matcherFromSource( sourceConfig ) {
 	switch ( sourceConfig.source ) {
@@ -84,13 +84,14 @@ export function matcherFromSource( sourceConfig ) {
 }
 
 /**
- * Given an attribute key, an attribute's schema, a block's raw content and the commentAttributes
- * returns the attribute value depending on its source definition of the given attribute key
+ * Given an attribute key, an attribute's schema, a block's raw content and the
+ * commentAttributes returns the attribute value depending on its source
+ * definition of the given attribute key.
  *
- * @param  {string} attributeKey        Attribute key
- * @param  {Object} attributeSchema     Attribute's schema
- * @param  {string} innerHTML           Block's raw content
- * @param  {Object} commentAttributes   Block's comment attributes
+ * @param {string} attributeKey      Attribute key.
+ * @param {Object} attributeSchema   Attribute's schema.
+ * @param {string} innerHTML         Block's raw content.
+ * @param {Object} commentAttributes Block's comment attributes.
  *
  * @returns {*} Attribute value.
  */
@@ -118,9 +119,9 @@ export function getBlockAttribute( attributeKey, attributeSchema, innerHTML, com
 /**
  * Returns the block attributes of a registered block node given its type.
  *
- * @param  {?Object} blockType  Block type
- * @param  {string}  innerHTML  Raw block content
- * @param  {?Object} attributes Known block attributes (from delimiters)
+ * @param {?Object} blockType  Block type.
+ * @param {string}  innerHTML  Raw block content.
+ * @param {?Object} attributes Known block attributes (from delimiters).
  *
  * @returns {Object} All block attributes.
  */
@@ -133,11 +134,12 @@ export function getBlockAttributes( blockType, innerHTML, attributes ) {
 }
 
 /**
- * Attempt to parse the innerHTML using using a supplied `deprecated` definition.
+ * Attempt to parse the innerHTML using using a supplied `deprecated`
+ * definition.
  *
- * @param  {?Object} blockType  Block type
- * @param  {string}  innerHTML  Raw block content
- * @param  {?Object} attributes Known block attributes (from delimiters)
+ * @param {?Object} blockType  Block type.
+ * @param {string}  innerHTML  Raw block content.
+ * @param {?Object} attributes Known block attributes (from delimiters).
  *
  * @returns {Object} Block attributes.
  */
@@ -162,9 +164,9 @@ export function getAttributesFromDeprecatedVersion( blockType, innerHTML, attrib
 /**
  * Creates a block with fallback to the unknown type handler.
  *
- * @param  {?String} name       Block type name
- * @param  {String}  innerHTML  Raw block content
- * @param  {?Object} attributes Attributes obtained from block delimiters
+ * @param {?String} name       Block type name.
+ * @param {string}  innerHTML  Raw block content.
+ * @param {?Object} attributes Attributes obtained from block delimiters.
  *
  * @returns {?Object} An initialized block object (if possible).
  */
@@ -232,7 +234,7 @@ export function createBlockWithFallback( name, innerHTML, attributes ) {
 /**
  * Parses the post content with a PegJS grammar and returns a list of blocks.
  *
- * @param  {String} content The post content
+ * @param {string} content The post content.
  *
  * @returns {Array} Block list.
  */

blocks/api/raw-handling/index.js

@@ -28,13 +28,14 @@ import shortcodeConverter from './shortcode-converter';
 /**
  * Converts an HTML string to known blocks. Strips everything else.
  *
- * @param  {String}       options.HTML        The HTML to convert.
- * @param  {String}       [options.plainText] Plain text version.
- * @param  {String}       [options.mode]      Handle content as blocks or inline content.
- *                                            * 'AUTO': Decide based on the content passed.
- *                                            * 'INLINE': Always handle as inline content, and return string.
- *                                            * 'BLOCKS': Always handle as blocks, and return array of blocks.
- * @param  {Array}         [options.tagName]  The tag into which content will be inserted.
+ * @param {string} [options.HTML]      The HTML to convert.
+ * @param {string} [options.plainText] Plain text version.
+ * @param {string} [options.mode]      Handle content as blocks or inline content.
+ *                                     * 'AUTO': Decide based on the content passed.
+ *                                     * 'INLINE': Always handle as inline content, and return string.
+ *                                     * 'BLOCKS': Always handle as blocks, and return array of blocks.
+ * @param {Array}  [options.tagName]   The tag into which content will be
+ *                                     inserted.
  *
  * @returns {Array|String} A list of blocks or a string, depending on `handlerMode`.
  */

blocks/api/raw-handling/utils.js

@@ -82,10 +82,10 @@ export function isAttributeWhitelisted( tag, attribute ) {
  * Checks if nodeName should be treated as inline when being added to tagName.
  * This happens if nodeName and tagName are in the same group defined in inlineWhitelistTagGroups.
  *
- * @param  {String}  nodeName Node name.
- * @param  {String}  tagName  Tag name.
+ * @param {string} nodeName Node name.
+ * @param {string} tagName  Tag name.
  *
- * @returns {Boolean} True if nodeName is inline in the context of tagName and
+ * @returns {boolean} True if nodeName is inline in the context of tagName and
  *                    false otherwise.
  */
 function isInlineForTag( nodeName, tagName ) {
@@ -197,9 +197,9 @@ export function isPlain( HTML ) {
 /**
  * Given node filters, deeply filters and mutates a NodeList.
  *
- * @param  {NodeList} nodeList The nodeList to filter.
- * @param  {Array}    filters  An array of functions that can mutate with the provided node.
- * @param  {Document} doc      The document of the nodeList.
+ * @param {NodeList} nodeList The nodeList to filter.
+ * @param {Array}    filters  An array of functions that can mutate with the provided node.
+ * @param {Document} doc      The document of the nodeList.
  */
 export function deepFilterNodeList( nodeList, filters, doc ) {
 	Array.from( nodeList ).forEach( ( node ) => {
@@ -219,10 +219,10 @@ export function deepFilterNodeList( nodeList, filters, doc ) {
 /**
  * Given node filters, deeply filters HTML tags.
  *
- * @param  {String} HTML    The HTML to filter.
- * @param  {Array}  filters An array of functions that can mutate with the provided node.
+ * @param {string} HTML    The HTML to filter.
+ * @param {Array}  filters An array of functions that can mutate with the provided node.
  *
- * @returns {String} The filtered HTML.
+ * @returns {string} The filtered HTML.
  */
 export function deepFilterHTML( HTML, filters = [] ) {
 	const doc = document.implementation.createHTMLDocument( '' );

blocks/api/registration.js

@@ -43,8 +43,8 @@ let defaultBlockName;
  * behavior. Once registered, the block is made available as an option to any
  * editor interface where blocks are implemented.
  *
- * @param  {string}   name     Block name
- * @param  {Object}   settings Block settings
+ * @param {string} name     Block name.
+ * @param {Object} settings Block settings.
  *
  * @returns {?WPBlock} The block, if it has been successfully registered;
  *                     otherwise `undefined`.
@@ -128,7 +128,7 @@ export function registerBlockType( name, settings ) {
 /**
  * Unregisters a block.
  *
- * @param  {string}   name Block name
+ * @param {string} name Block name.
  *
  * @returns {?WPBlock} The previous block value, if it has been successfully
  *                     unregistered; otherwise `undefined`.
@@ -148,7 +148,7 @@ export function unregisterBlockType( name ) {
 /**
  * Assigns name of block handling unknown block types.
  *
- * @param {string} name Block name
+ * @param {string} name Block name.
  */
 export function setUnknownTypeHandlerName( name ) {
 	unknownTypeHandlerName = name;
@@ -165,16 +165,16 @@ export function getUnknownTypeHandlerName() {
 }
 
 /**
- * Assigns the default block name
+ * Assigns the default block name.
  *
- * @param {string} name Block name
+ * @param {string} name Block name.
  */
 export function setDefaultBlockName( name ) {
 	defaultBlockName = name;
 }
 
 /**
- * Retrieves the default block name
+ * Retrieves the default block name.
  *
  * @returns {?string} Blog name.
  */
@@ -185,7 +185,7 @@ export function getDefaultBlockName() {
 /**
  * Returns a registered block type.
  *
- * @param  {string}  name Block name
+ * @param {string} name Block name.
  *
  * @returns {?Object} Block type.
  */
@@ -203,14 +203,14 @@ export function getBlockTypes() {
 }
 
 /**
- * Returns true if the block defines support for a feature, or false otherwise
+ * Returns true if the block defines support for a feature, or false otherwise.
  *
- * @param  {(String|Object)} nameOrType      Block name or type object
- * @param  {String}          feature         Feature to test
- * @param  {Boolean}         defaultSupports Whether feature is supported by
- *                                           default if not explicitly defined
+ * @param {(string|Object)} nameOrType      Block name or type object.
+ * @param {string}          feature         Feature to test.
+ * @param {boolean}         defaultSupports Whether feature is supported by
+ *                                          default if not explicitly defined.
  *
- * @returns {Boolean} Whether block supports feature.
+ * @returns {boolean} Whether block supports feature.
  */
 export function hasBlockSupport( nameOrType, feature, defaultSupports ) {
 	const blockType = 'string' === typeof nameOrType ?
@@ -225,12 +225,12 @@ export function hasBlockSupport( nameOrType, feature, defaultSupports ) {
 
 /**
  * Determines whether or not the given block is a reusable block. This is a
- * special block type that is used to point to a global block stored via the
- * API.
+ * special block type that is used to point to a global block stored via
+ * the API.
  *
- * @param {Object} blockOrType Block or Block Type to test
+ * @param {Object} blockOrType Block or Block Type to test.
  *
- * @returns {Boolean} Whether the given block is a reusable block.
+ * @returns {boolean} Whether the given block is a reusable block.
  */
 export function isReusableBlock( blockOrType ) {
 	return blockOrType.name === 'core/block';