Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

JSDoc fixes #4563

Merged
merged 4 commits into from
Jan 18, 2018
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion blocks/api/categories.js
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ const categories = [
];

/**
* Returns all the block categories
* Returns all the block categories.
*
* @returns {Array} Block categories.
*/
Expand Down
37 changes: 21 additions & 16 deletions blocks/api/factory.js
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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.
*/
Expand All @@ -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.
*/
Expand All @@ -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.
*/
Expand Down Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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.
*/
Expand Down
48 changes: 25 additions & 23 deletions blocks/api/parser.js
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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 ) {
Expand All @@ -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.
*/
Expand Down Expand Up @@ -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.
*/
Expand All @@ -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.
*/
Expand All @@ -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).
*/
Expand Down Expand Up @@ -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.
*/
Expand Down
15 changes: 8 additions & 7 deletions blocks/api/raw-handling/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
*/
Expand Down
18 changes: 9 additions & 9 deletions blocks/api/raw-handling/utils.js
Original file line number Diff line number Diff line change
Expand Up @@ -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 ) {
Expand Down Expand Up @@ -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 ) => {
Expand All @@ -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( '' );
Expand Down
36 changes: 18 additions & 18 deletions blocks/api/registration.js
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down Expand Up @@ -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`.
Expand All @@ -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;
Expand All @@ -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.
*/
Expand All @@ -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.
*/
Expand All @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This String should also be lowercased.

* @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 ?
Expand All @@ -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';
Expand Down
Loading