From 672e3091712a123cca6f20ef5c9c36122d30e580 Mon Sep 17 00:00:00 2001
From: "Alex A. Naanou" <alex.nanou@gmail.com>
Date: Tue, 12 Nov 2019 01:24:22 +0300
Subject: [PATCH] docs and notes...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>
---
 ui (gen4)/features/ui-widgets.js | 84 +++++++++++++++++++++-----------
 1 file changed, 55 insertions(+), 29 deletions(-)

diff --git a/ui (gen4)/features/ui-widgets.js b/ui (gen4)/features/ui-widgets.js
index f4296672..26bd50a6 100755
--- a/ui (gen4)/features/ui-widgets.js	
+++ b/ui (gen4)/features/ui-widgets.js	
@@ -1035,35 +1035,55 @@ var EditorActions = actions.Actions({
 		//		- ...
 	},
 
-	//
-	//	Make an editor dialog...
-	//	.makeEditor(spec, callback)
-	//		-> dialog
-	//
-	//	Make an editor dialog section...
-	//	.makeEditor(make, spec, callback)
-	//		-> make
-	//
-	//
-	// spec format:
-	// 	[
-	// 		<text>,
-	//
-	// 		{
-	// 			type: <type>,
-	//
-	// 			id: <str>,
-	// 			title: <str>,
-	//
-	// 			value: <str>,
-	//
-	// 			...
-	// 		},
-	//
-	// 		...
-	// 	]
-	//
 	makeEditor: ['- Interface/',
+		core.doc`Make editor dialog or editor section...
+
+			Make an editor dialog...
+			.makeEditor(spec)
+			.makeEditor(spec, callback)
+				-> dialog
+			
+			Make an editor dialog section...
+			.makeEditor(make, spec)
+			.makeEditor(make, spec, callback)
+				-> make
+
+
+		 spec format:
+			[
+				// make a simple text element...
+				//
+				// same as: make(<text>)
+				<text>,
+				[<text>],
+		
+				// call make(..) with args...
+				//
+				// same as: make(...[ .. ])
+				//
+				// NOTE: to explicitly pass an array object to make wrap it 
+				//		in an array, e.g. [['text', 'value']]
+				[ .. ],
+		
+
+				// make a field...
+				{
+					type: <type>,
+		
+					id: <str>,
+					title: <str>,
+		
+					value: <str>,
+		
+					...
+				},
+		
+				...
+			]
+
+
+		
+		`,
 		makeUIDialog(function(spec, callback){
 			var _make = function(make, spec){
 				var that = this
@@ -1084,11 +1104,17 @@ var EditorActions = actions.Actions({
 			var _callback = callback
 				&& function(spec){
 					return callback(
+						// get the field-value pairs...
 						spec.reduce(function(res, e){
 							var id = e.id || e.title
 							id != undefined
 								&& (res[id] = e.value)
-							return res }, {}) ) } 
+							return res }, {}), 
+						// NOTE: technically we do not need to pass this
+						// 		through as we are mutating the data inside
+						// 		but passing it here is cleaner than forcing
+						// 		the user to get it via closure...
+						spec) } 
 			
 			return arguments[0] instanceof Function?
 				// inline...