Index: trunk/src/plugins/io_easyeda/read.c
===================================================================
--- trunk/src/plugins/io_easyeda/read.c	(revision 10718)
+++ trunk/src/plugins/io_easyeda/read.c	(revision 10719)
@@ -208,6 +208,8 @@
 	dst = tmp->value.str; \
 } while(0)
 
+/*** svgpath rendering ***/
+
 static svgpath_cfg_t pathcfg;
 typedef struct {
 	read_ctx_t *ctx;
@@ -241,6 +243,7 @@
 	}
 }
 
+/* Create an (svg)path as a line approximation within parent */
 static int easyeda_mkpath(read_ctx_t *ctx, csch_cgrp_t *parent, const char *pathstr, gdom_node_t *nd, const char *penname, int filled)
 {
 	path_ctx_t pctx;
@@ -259,6 +262,7 @@
 	return svgpath_render(&pathcfg, &pctx, pathstr);
 }
 
+/* Set cobj locked if the locked subtree says so */
 static int easyeda_apply_lock(read_ctx_t *ctx, gdom_node_t *nd, csch_chdr_t *cobj)
 {
 	long locked;
@@ -290,6 +294,7 @@
 	return 0;
 }
 
+/* reconfigure an existing text object to the required alignemnt ("anchor") */
 static void easyeda_text_anchor(read_ctx_t *ctx, csch_text_t *txt, const char *anchor, gdom_node_t *error_nd)
 {
 	switch(*anchor) {
@@ -302,6 +307,7 @@
 	}
 }
 
+/* Create a rail symbol, e.g. Vcc */
 static void easyeda_mkrail(read_ctx_t *ctx, csch_cgrp_t *sym, const char *netname, gdom_node_t *src_nd)
 {
 	csch_source_arg_t *src;
@@ -327,6 +333,7 @@
 	EASYEDA_FILL_NEVER
 } easyede_fill_t;
 
+/* parse and draw a subtree that has a path in it, with or without fill */
 static int easyeda_parse_path_(read_ctx_t *ctx, csch_cgrp_t *parent, gdom_node_t *nd, int group, easyede_fill_t fill)
 {
 	const char *pathstr, *penname;
Index: trunk/src/plugins/io_easyeda/read_hi_pro_draw.c
===================================================================
--- trunk/src/plugins/io_easyeda/read_hi_pro_draw.c	(revision 10718)
+++ trunk/src/plugins/io_easyeda/read_hi_pro_draw.c	(revision 10719)
@@ -147,7 +147,7 @@
 		GET_ARG_STR(name, obj, 1, "easypro_parse_part: name", return -1);
 		easypro_add_sym(ctx, name, parent);
 	}
-	else if (ctx->pro_want_slot == -1) {
+	else if (ctx->pro_want_slot == -1) { /* create all slots, offseted by bbox */
 		double x1, x2/*, y1, y2*/;
 
 		coords = gdom_hash_get(bbox, easy_BBOX);
@@ -166,7 +166,7 @@
 		if (ctx->pro_slot > 1)
 			ctx->alien.ox += (x2-x1)*2;
 	}
-	else if (ctx->pro_slot > ctx->pro_want_slot)
+	else if (ctx->pro_slot > ctx->pro_want_slot) /* read only the first */
 		ctx->pro_stop = 1; /* don't read any more slots */
 
 	ctx->pro_last = *parent;
@@ -602,6 +602,8 @@
 
 	filled = easypro_style_filled(ctx, obj, sty);
 
+	/* svgpath happens to implement an approximator, reuse that */
+
 	easyeda_svgpath_setup();
 
 	pctx.ctx = ctx;
@@ -807,6 +809,7 @@
 		return -1;
 	}
 
+	/* always embed from symhash */
 	dst = csch_cgrp_dup(ctx->sheet, &ctx->sheet->direct, src, 0);
 	if (dst == NULL) {
 		error_at(ctx, obj, ("easypro_parse_component: failed to copy symbol '%s' from the symtab to the sheet\n", symname));
Index: trunk/src/plugins/io_easyeda/read_hi_pro_glue.c
===================================================================
--- trunk/src/plugins/io_easyeda/read_hi_pro_glue.c	(revision 10718)
+++ trunk/src/plugins/io_easyeda/read_hi_pro_glue.c	(revision 10719)
@@ -29,6 +29,10 @@
 /* high level for the 'std' format - included from read.c; glue layer
    between draw and io */
 
+/* Load a zip-unpacked sheet file from fn into sheet with symbols coming
+   from symtab. Unused args for now:
+   - user_name: user assigned name, from the project file
+   - loclib_sym: sheet-local symbol library (but we are embedding instead) */
 static int easypro_load_sheet(const char *user_name, const char *fn, csch_sheet_t *sheet, csch_cgrp_t *loclib_sym, htsp_t *symtab)
 {
 	read_ctx_t ctx = {0};
@@ -88,8 +92,8 @@
 	return rv;
 }
 
-/* Load a symbol using ctx into resgrp; if resgrp is NULL, allocate a
-   new group in sheet */
+/* Load a symbol from a fully prepared ctx into resgrp; if resgrp is
+   NULL, allocate a new group in sheet */
 static csch_cgrp_t *easypro_load_sym(read_ctx_t *ctx, csch_cgrp_t *resgrp)
 {
 	csch_source_arg_t *src;
@@ -137,7 +141,8 @@
 	return resgrp;
 }
 
-/* Load a symbol into a group; if existing is NULL, allocate new */
+/* Load a symbol from an open file into a group; if existing is NULL, allocate
+   new */
 csch_cgrp_t *io_easypro_load_grp_into(FILE *f, const char *fn, csch_sheet_t *sheet, csch_cgrp_t *existing, int slotno)
 {
 	read_ctx_t ctx = {0};
@@ -168,6 +173,10 @@
 }
 
 
+/* Lazy heuristics to figure if a file looks like a zip; this is not
+   100% correct: there's no guarantee the file starts with a PK block,
+   but one from the end would need to be picked (but that may have a
+   max 64k comment so it would need to be searched backward... */
 static int easypro_is_file_zip(FILE *f)
 {
 	char buf[4];
@@ -201,6 +210,7 @@
 	return tmp.array;
 }
 
+/* return 0 if f/fn looks like a symbol file */
 static int easypro_test_parse_sym(FILE *f, const char *fn, const char *fmt, csch_plug_io_type_t type)
 {
 	char line_[256], *line;
@@ -227,6 +237,8 @@
 	return -1;
 }
 
+/* returns 0 if f/fn looks like a zip that may contain the type-requested
+   kind of data; fill in is_sym if the file is really a symbol and not a sheet. */
 static int easypro_test_parse_zip(FILE *f, const char *fn, const char *fmt, csch_plug_io_type_t type, int *is_sym)
 {
 	int res = -1;
@@ -244,11 +256,11 @@
 	if (fc != NULL) {
 		char *line, buf[1024];
 		while((line = fgets(buf, sizeof(buf), fc)) != NULL) {
-			if (strstr(line, "project.json") != NULL) {
+			if (strstr(line, "project.json") != NULL) { /* sheet */
 				res = 0;
 				break;
 			}
-			else if (strstr(line, "device.json") != NULL) {
+			else if (strstr(line, "device.json") != NULL) { /* symbol */
 				*is_sym = 1;
 				res = 0;
 				break;
@@ -349,7 +361,8 @@
 
 
 
-/* read the project file and map sheets and symbols to load */
+/* read the zip-unpacked project file and map sheets and symbols to load 
+   into bnd->syms and bnd->sheets as pairs of strings */
 static int easypro_load_zip_sheet_init(easypro_bundle_t *bnd, csch_sheet_t *sheet)
 {
 	char *fn, *sname = NULL;
@@ -385,11 +398,12 @@
 			case NJSON_SEM_EV_more: continue;
 			case NJSON_SEM_EV_eof: case NJSON_SEM_EV_error: break; /* can't happen */
 			case NJSON_SEM_EV_OBJECT_BEGIN:
-				if (level == 1) {
+				if (level == 1) { /* remember which main tree we are in */
 					if (strcmp(jctx.name, "schematics") == 0) tmain = M_SCH;
 					else if (strcmp(jctx.name, "symbols") == 0) tmain = M_SYM;
 				}
 				if ((level == 2) && ((tmain == M_SYM) || (tmain == M_SCH))) {
+					/* remember the name of the object subtree */
 					if (sname != NULL) free(sname);
 					sname = rnd_strdup(jctx.name);
 /*					rnd_trace(" sname: %s\n", jctx.name);*/
@@ -447,6 +461,8 @@
 						if (level != 5) break;
 						/* reading items of a schematic block */
 /*						rnd_trace("  [%d] sch atom: %s\n", level, jctx.name);*/
+
+						/* remember a few of the sch data fields for flush to use above */
 						if (strcmp(jctx.name, "id") == 0) {
 							if (jctx.type != NJSON_SEM_TYPE_NUMBER) {
 								rnd_message(RND_MSG_ERROR, "easypro sheet init: project.json parse error: sch id must be a number at %ld:%ld\n", jctx.njs.lineno, jctx.njs.col);
@@ -480,14 +496,16 @@
 	return res;
 }
 
+/* load the next sheet from bnd into sheet */
 static int easypro_load_zip_sheet(easypro_bundle_t *bnd, csch_sheet_t *sheet)
 {
 	csch_cgrp_t *loclib_sym;
 
-	if (!bnd->sheet_loader_inited) {
+	if (!bnd->sheet_loader_inited) { /* setup bnd before the first sheet */
 		long n;
 		read_ctx_t symctx = {0};
 
+		/* parse the project file */
 		if (easypro_load_zip_sheet_init(bnd, sheet) != 0)
 			return -1;
 
@@ -497,6 +515,7 @@
 		}
 		bnd->sheet_loader_inited = 1;
 
+		/* load all symbols into temporary symsheet and build a symhash */
 		csch_sheet_init(&bnd->symsheet, NULL);
 		bnd->symsheet_inited = 1;
 
@@ -548,7 +567,7 @@
 
 	bnd->sheet_idx += 2;
 	if (bnd->sheet_idx >= bnd->sheets.used)
-		return 1;
-	return 0;
+		return 1; /* success, no more sheet */
+	return 0; /* success, reiterate for the next sheet */
 }
 
Index: trunk/src/plugins/io_easyeda/read_hi_pro_io.c
===================================================================
--- trunk/src/plugins/io_easyeda/read_hi_pro_io.c	(revision 10718)
+++ trunk/src/plugins/io_easyeda/read_hi_pro_io.c	(revision 10719)
@@ -34,9 +34,11 @@
 	return io_easypro_load_grp_into(f, fn, sheet, NULL, 1);
 }
 
-
+/* True when the user configured zip commands */
 #define CAN_UNZIP ((io_easyeda_conf.plugins.io_easyeda.zip_list_cmd != NULL) && (*io_easyeda_conf.plugins.io_easyeda.zip_list_cmd != '\0'))
 
+/* Accept zip files that are symbols for both symbol and sheet load or
+   sheets for sheet load */
 int io_easypro_test_parse(FILE *f, const char *fn, const char *fmt, csch_plug_io_type_t type)
 {
 	if (easypro_test_parse_sym(f, fn, fmt, type) == 0)
@@ -57,7 +59,7 @@
 	return -1;
 }
 
-
+/* load first/next file from the zip */
 int io_easypro_load_sheet_bundled(void *cookie, FILE *f, const char *fn, csch_sheet_t *dst)
 {
 	easypro_bundle_t *bnd = cookie;
@@ -66,7 +68,10 @@
 	return easypro_load_zip_sheet(bnd, dst);
 }
 
-/* called only for sheets */
+/* Bundled is called only for sheets; symbols are not bundled and are
+   loaded through io_easypro_load_grp() by plug_io. If the file is accepted
+   it is also unpacked into a temp dir left there for sheet loader to read
+   it file by file */
 void *io_easypro_test_parse_bundled(FILE *f, const char *fn, const char *fmt, csch_plug_io_type_t type)
 {
 	int is_sym, res;
@@ -85,7 +90,7 @@
 	bnd->fn = fn;
 	bnd->is_sym = is_sym;
 
-	/* unpack */
+	/* unpack: create a temp dir... */
 	if (!io_easyeda_conf.plugins.io_easyeda.debug.unzip_static) {
 		if (rnd_mktempdir(NULL, &bnd->tempdir, "easypro") != 0) {
 			free(bnd);
@@ -96,6 +101,7 @@
 	else
 		bnd->dir = "/tmp/easypro";
 
+	/* ... cd to it and unpacl there with full path to the zip */
 	prefix[0] = "cd ";
 	prefix[1] = bnd->dir;
 	prefix[2] = ";";
Index: trunk/src/plugins/io_easyeda/read_hi_std.c
===================================================================
--- trunk/src/plugins/io_easyeda/read_hi_std.c	(revision 10718)
+++ trunk/src/plugins/io_easyeda/read_hi_std.c	(revision 10719)
@@ -269,7 +269,8 @@
 	return term;
 }
 
-
+/* a netflag is a netname with some graphics, e.g. the VCC rail; all graphics
+   specified by the file */
 static int easystd_parse_netflag(read_ctx_t *ctx, csch_cgrp_t *parent, gdom_node_t *nd)
 {
 	csch_source_arg_t *src;
@@ -427,7 +428,7 @@
 }
 
 
-
+/* filled and unfilled polygons from a coord list */
 static int easystd_parse_poly_(read_ctx_t *ctx, csch_cgrp_t *parent, gdom_node_t *nd, int allow_fill, const char *penname)
 {
 	const char *fill;
@@ -507,6 +508,7 @@
 	return easystd_parse_poly_(ctx, parent, nd, 1, "bus");
 }
 
+/* This is really a bus terminal */
 static int easystd_parse_busentry(read_ctx_t *ctx, csch_cgrp_t *parent, gdom_node_t *nd)
 {
 	double x1, y1, x2, y2;
@@ -696,9 +698,10 @@
 	ex = x + rx;
 	ey = y;
 
+	/* svgpath happens to have an elliptical approximator and can handle
+	   filled/unfilled already */
 	easyeda_svgpath_setup();
 
-
 	pctx.ctx = ctx;
 	pctx.nd = nd;
 	pctx.penname = penname;
@@ -850,6 +853,7 @@
 	return -1;
 }
 
+/* Draw all shapes of a sheet, single pass (call it twice with ctx->pass 1 and 2 */
 static int easystd_parse_shapes(read_ctx_t *ctx, csch_cgrp_t *parent, gdom_node_t *nd)
 {
 	if (nd != NULL) {
@@ -871,12 +875,13 @@
 	return 0;
 }
 
+/* Parse sheet_root into ctx->sheet */
 static int easystd_parse_sheet(read_ctx_t *ctx, gdom_node_t *sheet_root)
 {
 	gdom_node_t *nd, *data_str;
 	int res;
 
-	rnd_trace("LOAD SHEET\n");
+/*	rnd_trace("LOAD SHEET\n");*/
 
 	/* verify docType */
 	HASH_GET_SUBTREE(nd,   sheet_root, easy_docType, GDOM_STRING,   return -1);
@@ -914,6 +919,7 @@
 	return res;
 }
 
+/* parse symbol from sym_root into resgrp */
 static csch_cgrp_t *easystd_parse_grp_(read_ctx_t *ctx, gdom_node_t *sym_root, csch_cgrp_t *resgrp)
 {
 	int rv = 0;
@@ -1035,6 +1041,7 @@
 	return -1;
 }
 
+/* doctype is an integer that identifies what the json is about */
 static int easystd_get_doctype(char *stray, FILE *f, char *buf, long buf_len)
 {
 	char *line = stray, *end;
Index: trunk/src/plugins/io_easyeda/read_low_pro.c
===================================================================
--- trunk/src/plugins/io_easyeda/read_low_pro.c	(revision 10718)
+++ trunk/src/plugins/io_easyeda/read_low_pro.c	(revision 10719)
@@ -20,7 +20,9 @@
 */
 
 /* These functions parse "EasyEDA pro" file formats; these semi-json files
-   differ from the "EasyEDA std" variant */
+   differ from the "EasyEDA std" variant. Subtrees don't need to be
+   expanded/replaced but the while file needs to be reshaped a bit to
+   become a valid json array */
 
 #include "read_low_pro.h"