Skip to content

Commit

Permalink
JSDoc fixes
Browse files Browse the repository at this point in the history
  • Loading branch information
@ntwb
ntwb committed Jan 18, 2018
1 parent b8566d7 commit 596ff36
Show file tree
Hide file tree
Showing 49 changed files with 659 additions and 613 deletions.
2 changes: 1 addition & 1 deletion blocks/api/categories.js
View file
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
View file
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
View file
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
View file
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
View file
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
View file
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.
* @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

0 comments on commit 596ff36

Please sign in to comment.