From 1800bba95537b5314daae491244444dc8f7a23d7 Mon Sep 17 00:00:00 2001
From: Riad Benguella <benguella@gmail.com>
Date: Tue, 9 May 2017 10:04:41 +0100
Subject: [PATCH] Parser: Adds comments to attributes parsing

---
 blocks/api/parser.js |  3 +++
 blocks/api/query.js  | 18 +++++++++++++++---
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/blocks/api/parser.js b/blocks/api/parser.js
index e30edd50eec00..4f7a4d5644284 100644
--- a/blocks/api/parser.js
+++ b/blocks/api/parser.js
@@ -20,6 +20,9 @@ import { createBlock } from './factory';
  * @return {Object}                All block attributes
  */
 export function getBlockAttributes( blockSettings, rawContent, attributes ) {
+	// The blockSettings.attributes contains the definition of each attribute
+	// depending on its "source", we retrieve its value from the comment attribute
+	// or by parsing the block content
 	const computedAttributes = reduce( blockSettings.attributes, ( memo, attribute, key ) => {
 		if ( attribute.source === 'metadata' ) {
 			memo[ key ] = attributes[ attribute.name || key ];
diff --git a/blocks/api/query.js b/blocks/api/query.js
index 98f03c41782c6..bae58c1e29d20 100644
--- a/blocks/api/query.js
+++ b/blocks/api/query.js
@@ -31,6 +31,11 @@ const addDescriptor = ( description ) => ( memo ) => {
 	return Object.assign( memo, description );
 };
 
+// Source descriptors
+// Each one of these functions defines how to retrieve the attribute value
+//
+//  - the descriptor sets "source: content" and a parse function for attributes parsed from block content
+//  - the descriptor sets "source: metadata" and an attribute name for attributes stored in the block comment
 const attr = ( ...args ) => addDescriptor( { source: 'content', parse: originalAttr( ...args ) } );
 const prop = ( ...args ) => addDescriptor( { source: 'content', parse: originalProp( ...args ) } );
 const html = ( ...args ) => addDescriptor( { source: 'content', parse: originalHtml( ...args ) } );
@@ -44,13 +49,20 @@ const query = ( selector, descriptor ) => {
 	} );
 };
 
-const accumulateOn = ( description ) => {
+/**
+ * Takes an argument description and returns a chainable API to describe the current attribute
+ *
+ * @param  {?Object} description The argument description
+ *
+ * @return {Object}              descriptors chainable API
+ */
+const getChainableAPI = ( description ) => {
 	return reduce( { attr, prop, html, text, query, children, metadata }, ( memo, fct, key ) => {
 		const wrappedFct = ( ...args ) => {
 			const accumulator = fct( ...args );
 			const newDescription = accumulator( description || {} );
 			return {
-				...accumulateOn( newDescription ),
+				...getChainableAPI( newDescription ),
 				__description: newDescription
 			};
 		};
@@ -60,4 +72,4 @@ const accumulateOn = ( description ) => {
 	}, {} );
 };
 
-export default accumulateOn();
+export default getChainableAPI();