diff --git a/ui/bookmarks.js b/ui/bookmarks.js
index f6d2aee9..19fb995f 100755
--- a/ui/bookmarks.js
+++ b/ui/bookmarks.js
@@ -5,6 +5,8 @@
 **********************************************************************/
 
 // list of bookmarked gids...
+//
+// NOTE: this must be sorted in the same order as DATA.order
 var BOOKMARKS= [] 
 
 // bookmark data
@@ -78,14 +80,6 @@ var toggleBookmark = makeMarkToggler(
 			// add a bookmark...
 			if(action == 'on'){
 				if(BOOKMARKS.indexOf(gid) == -1){
-					/*
-					BOOKMARKS.push(gid)
-					// XXX is this too expensive???
-					// 		...a way to avoid sorting is to:
-					// 			BOOKMARKS.splice(
-					// 				getGIDBefore(gid, BOOKMARKS)+1, 0, gid)
-					BOOKMARKS.sort(imageOrderCmp)
-					*/
 					insertGIDToPosition(gid, BOOKMARKS)
 				}
 
diff --git a/ui/data.js b/ui/data.js
index b28f7836..52025f2e 100755
--- a/ui/data.js
+++ b/ui/data.js
@@ -14,14 +14,35 @@
 // Major version change mean a significant incompatibility.
 //
 // Minor version changes mean some detail changed and can be handled
-// by it's specific handler seamlessly.
+// by it's specific handler seamlessly. Backwards compatible.
+//
+//
+// For more info see:
+// 	DATA			- main data
+// 	IMAGES			- image data
+// 	MARKED			- marks data
+// 	BOOKMARKS		- bookmarks data
+// 	BOOKMARKS_DATA	- bookmarks metadata
+//
 //
 // Changes:
-// 	2.0 	- completely and incompatible new format
-// 			- use convertDataGen1(..) to update old data
-// 	2.1		- MARKED now maintained sorted
-// 			- will auto-update on loading marks to 2.1 of 2.1 data, will
-// 			  need a re-save
+// 	none - Gen1 data format, mostly experimental,
+// 			- has no explicit version set,
+// 			- not used for real data.
+// 	2.0 - Gen3 data format, still experimental,
+// 			- completely and incompatibly new structure,
+// 			- use convertDataGen1(..) to convert Gen1 to 2.0 
+// 			- auto-convert form gen1 on load...
+// 			- used for my archive, not public,
+// 	2.1 - Minor update to format spec,	
+// 			- MARKED now maintained sorted, live,
+// 			- will auto-sort marks on load of 2.0 data and change 
+// 			  data version to 2.1, will need a re-save,
+//
+// NOTE: Gen1 and Gen3 refer to code generations rather than data format
+// 		iterations, Gen2 is skipped here as it is a different project 
+// 		(PortableMag) mostly built on the same code base as 
+// 		ImageGrid.Viewer
 var DATA_VERSION = '2.1'
 
 
diff --git a/ui/marks.js b/ui/marks.js
index 97f321c1..c5e4894c 100755
--- a/ui/marks.js
+++ b/ui/marks.js
@@ -6,6 +6,7 @@
 
 //var DEBUG = DEBUG != null ? DEBUG : true
 
+// NOTE: this must be sorted in the same order as DATA.order
 var MARKED = []
 
 var MARKED_FILE_DEFAULT = 'marked.json'
@@ -562,7 +563,7 @@ var loadFileMarks = makeFileLoader(
 					// XXX is this the correct way to do this???
 					DATA.version = DATA_VERSION
 
-					console.warn('Marks: sort: done ('+( t1 - t0 )+'ms) -- resave the data.')
+					console.warn('Marks: sort: done ('+( t1 - t0 )+'ms) -- re-save the data.')
 				}, 0)
 			}
 		},