Index: layersel/layersel.c
===================================================================
--- layersel/layersel.c	(revision 8546)
+++ layersel/layersel.c	(revision 8547)
@@ -26,6 +26,7 @@
 
 #define hex2bin(str) ((hex2bin_((str)[0])) << 4 | hex2bin_((str)[1]))
 
+/* draw a visibility box: filled or partially filled with layer color */
 static GtkWidget *layer_vis_box(int filled, const char *rgb)
 {
 	GdkPixbuf *pixbuf;
@@ -67,7 +68,7 @@
 	return image;
 }
 
-/*** Sync ***/
+/*** Sync: make the GUI look like internal states ***/
 
 static void layer_vis_sync(layersel_layer_t *lsl)
 {
@@ -101,6 +102,8 @@
 		gtk_widget_show_all(lsg->grp_closed);
 		gtk_widget_set_no_show_all(lsg->grp_closed, 1);
 		pcb_gtk_widget_hide_all(lsg->grp_open);
+
+		/* a closed group has visibility boxes displayed, pick one to show */
 		if (lsg->vis_on != NULL) {
 			if (lsg->on) {
 				gtk_widget_show(lsg->vis_on);
@@ -200,6 +203,7 @@
 
 /*** Row builder ***/
 
+/* Create a hbox with on/off visibility boxes packed in, pointers returned in *on, *off */
 static GtkWidget *build_visbox(const char *color, GtkWidget **on, GtkWidget **off)
 {
 	GtkWidget *vis_box = gtkc_hbox_new(0, 0);
@@ -210,6 +214,7 @@
 	return vis_box;
 }
 
+/* Create a hbox of a layer within an expanded group */
 static GtkWidget *build_layer(layersel_grp_t *lsg, layersel_layer_t *lsl, const char *name)
 {
 	GtkWidget *vis_box, *vis_ebox, *ly_name_bx, *lab;
@@ -222,13 +227,12 @@
 	vis_ebox = wrap_bind_click(vis_box, G_CALLBACK(layer_vis_press_cb), lsl);
 	gtk_box_pack_start(GTK_BOX(lsl->box), vis_ebox, FALSE, FALSE, 0);
 
+	/* selectable layer name*/
 	ly_name_bx = gtkc_hbox_new(0, 0);
 	lsl->name_box = wrap_bind_click(ly_name_bx, G_CALLBACK(layer_select_press_cb), lsl);
-
 	lab = gtk_label_new(name);
 	gtk_box_pack_start(GTK_BOX(ly_name_bx), lab, TRUE, TRUE, 2);
 	gtk_box_pack_start(GTK_BOX(lsl->box), lsl->name_box, TRUE, TRUE, 10);
-
 	gtk_misc_set_alignment(GTK_MISC(lab), 0, 0.5);
 
 	layer_vis_sync(lsl);
@@ -236,6 +240,7 @@
 	return lsl->box;
 }
 
+/* Creating a group enrty (both open and closed state); after layers are added, finish() needs to be called */
 static GtkWidget *build_group_start(pcb_gtk_layersel_t *ls, layersel_grp_t *lsg, const char *gname, int has_group_vis)
 {
 	GtkWidget *gn_vert, *vlabel, *opn, *cld;
@@ -265,7 +270,7 @@
 	gtk_box_pack_start(GTK_BOX(lsg->grp_open), opn, FALSE, FALSE, 0);
 	gtk_box_pack_start(GTK_BOX(lsg->grp_open), lsg->layers, TRUE, TRUE, 0);
 
-	/* install group name */
+	/* install group name - vertical (for when the group is open) */
 	vlabel = gtk_label_new(gname);
 	gtk_label_set_angle(GTK_LABEL(vlabel), 90);
 	gtk_box_pack_start(GTK_BOX(gn_vert), vlabel, TRUE, TRUE, 0);
@@ -272,6 +277,7 @@
 	gtk_misc_set_alignment(GTK_MISC(vlabel), 0, 1);
 	gtk_widget_set_size_request(vlabel, 32, 1);
 
+	/* install group name - vertical (for when the group is closed) */
 	if (has_group_vis) {
 		GtkWidget *vis;
 		vis = wrap_bind_click(build_visbox("#ff0000", &lsg->vis_on, &lsg->vis_off), G_CALLBACK(group_vis_press_cb), lsg);
@@ -283,6 +289,7 @@
 	return lsg->grp_row;
 }
 
+/* finish creating a group - call after layers are added */
 static void build_group_finish(layersel_grp_t *lsg)
 {
 	/* Make sure gtk_show_all() won't mess with our hardwired hide/show */
@@ -291,6 +298,7 @@
 	gtk_widget_set_no_show_all(lsg->grp_open, 1);
 }
 
+/* Create a group that has a real layer group in core, add all layers */
 static GtkWidget *build_group_real(pcb_gtk_layersel_t *ls, layersel_grp_t *lsg, const char *gname)
 {
 	int n;