Update inline documentation in blocks/api.

blocks/api/factory.js

@@ -10,20 +10,24 @@ import { get, castArray, findIndex, isObjectLike } from 'lodash';
 import { getBlockSettings } from './registration';
 
 /**
- * Returns a block object given its type and attributes
+ * Returns a block object given its type and attributes.
  *
  * @param  {String} blockType   BlockType
  * @param  {Object} attributes  Block attributes
  * @return {Object}             Block object
  */
 export function createBlock( blockType, attributes = {} ) {
+	// Get the type definition associated with a registered block.
 	const blockSettings = getBlockSettings( blockType );
 
+	// Do we need this? What purpose does it have?
 	let defaultAttributes;
 	if ( blockSettings ) {
 		defaultAttributes = blockSettings.defaultAttributes;
 	}
 
+	// Blocks are stored with a unique ID, the assigned type name,
+	// and the block attributes.
 	return {
 		uid: uuid(),
 		blockType,
@@ -35,7 +39,7 @@ export function createBlock( blockType, attributes = {} ) {
 }
 
 /**
- * Switch a block into one or more blocks of the new block type
+ * Switch a block into one or more blocks of the new block type.
  *
  * @param  {Object} block      Block object
  * @param  {string} blockType  BlockType
@@ -52,7 +56,7 @@ export function switchToBlockType( block, blockType ) {
 		transformationsTo.find( t => t.blocks.indexOf( blockType ) !== -1 ) ||
 		transformationsFrom.find( t => t.blocks.indexOf( block.blockType ) !== -1 );
 
-	// If no valid transformation, stop.  (How did we get here?)
+	// Stop if there is no valid transformation. (How did we get here?)
 	if ( ! transformation ) {
 		return null;
 	}

blocks/api/parser.js

@@ -47,7 +47,8 @@ export function parseBlockAttributes( rawContent, blockSettings ) {
  * @return {Object}                All block attributes
  */
 export function getBlockAttributes( blockSettings, rawContent, attributes ) {
-	// Merge any attributes from comment delimiters with block implementation
+	// Merge any attributes present in comment delimiters with those
+	// that are specified in the block implementation.
 	attributes = attributes || {};
 	if ( blockSettings ) {
 		attributes = {
@@ -69,18 +70,18 @@ export function getBlockAttributes( blockSettings, rawContent, attributes ) {
  * @return {?Object}            An initialized block object (if possible)
  */
 export function createBlockWithFallback( blockType, rawContent, attributes ) {
-	// Use type from block content, otherwise find unknown handler
+	// Use type from block content, otherwise find unknown handler.
 	blockType = blockType || getUnknownTypeHandler();
 
-	// Try finding settings for known block type, else again fall back
+	// Try finding settings for known block type, else fall back again.
 	let blockSettings = getBlockSettings( blockType );
 	const fallbackBlockType = getUnknownTypeHandler();
 	if ( ! blockSettings ) {
 		blockType = fallbackBlockType;
 		blockSettings = getBlockSettings( blockType );
 	}
 
-	// Include in set only if settings were determined
+	// Include in set only if settings were determined.
 	// TODO do we ever expect there to not be an unknown type handler?
 	if ( blockSettings && ( rawContent.trim() || blockType !== fallbackBlockType ) ) {
 		// TODO allow blocks to opt-in to receiving a tree instead of a string.
@@ -123,27 +124,30 @@ export function parseWithTinyMCE( content ) {
 		}
 	);
 
-	// Create a custom HTML schema
+	// Create a custom HTML schema.
 	const schema = new tinymce.html.Schema();
-	// Add <wp-block> "tags" to our schema
+
+	// Add <wp-block> "tags" to our schema.
 	schema.addCustomElements( 'wp-block' );
-	// Add valid <wp-block> "attributes" also
+
+	// Add valid <wp-block> "attributes" also.
 	schema.addValidElements( 'wp-block[slug|attributes]' );
-	// Initialize the parser with our custom schema
+
+	// Initialize the parser with our custom schema.
 	const parser = new tinymce.html.DomParser( { validate: true }, schema );
 
-	// Parse the content into an object tree
+	// Parse the content into an object tree.
 	const tree = parser.parse( content );
 
 	// Create a serializer that we will use to pass strings to blocks.
 	// TODO: pass parse trees instead, and verify them against the markup
 	// shapes that each block can accept.
 	const serializer = new tinymce.html.Serializer( { validate: true }, schema );
 
-	// Walk the tree and initialize blocks
+	// Walk the tree and initialize blocks.
 	const blocks = [];
 
-	// Store markup we found in between blocks
+	// Store markup we found in between blocks.
 	let contentBetweenBlocks = null;
 	function flushContentBetweenBlocks() {
 		if ( contentBetweenBlocks && contentBetweenBlocks.firstChild ) {
@@ -164,19 +168,19 @@ export function parseWithTinyMCE( content ) {
 	do {
 		if ( currentNode.name === 'wp-block' ) {
 			// Set node type to document fragment so that the TinyMCE
-			// serializer doesn't output its markup
+			// serializer doesn't output its markup.
 			currentNode.type = 11;
 
 			// Serialize the content
 			const rawContent = serializer.serialize( currentNode );
 
-			// Retrieve the attributes from the <wp-block> tag
+			// Retrieve the attributes from the <wp-block> tag.
 			const nodeAttributes = currentNode.attributes.reduce( ( memo, attr ) => {
 				memo[ attr.name ] = attr.value;
 				return memo;
 			}, {} );
 
-			// Retrieve the block attributes from the original delimiters
+			// Retrieve the block attributes from the original delimiters.
 			const attributesMatcher = /([a-z0-9_-]+)(="([^"]*)")?/g;
 			const blockAttributes = {};
 			let match;
@@ -187,7 +191,7 @@ export function parseWithTinyMCE( content ) {
 				}
 			} while ( !! match );
 
-			// Try to create the block
+			// Try to create the block.
 			const block = createBlockWithFallback(
 				nodeAttributes.slug,
 				rawContent,

blocks/api/serializer.js

@@ -52,7 +52,7 @@ export function getCommentAttributes( realAttributes, expectedAttributes ) {
 		Object.keys( expectedAttributes )
 	);
 
-	// Serialize the comment attributes
+	// Serialize the comment attributes as `key="value"`.
 	return keys.reduce( ( memo, key ) => {
 		const value = realAttributes[ key ];
 		if ( undefined === value ) {
@@ -64,7 +64,7 @@ export function getCommentAttributes( realAttributes, expectedAttributes ) {
 }
 
 /**
- * Takes a block list and returns the serialized post content
+ * Takes a block list and returns the serialized post content.
  *
  * @param  {Array}  blocks Block list
  * @return {String}        The post content