 		# may need to roll over a pack here if we are inserting packs
 		db.docHistory.insert update, callback
 
+	# The following function implements a method like a mongo find, but
+	# which expands any documents containing a 'pack' field into
+	# multiple values
+	#
+	#  e.g.  a single update looks like
+	#
+	#   {
+	#     "doc_id" : 549dae9e0a2a615c0c7f0c98,
+	#     "project_id" : 549dae9c0a2a615c0c7f0c8c,
+	#     "op" : [ {"p" : 6981,	"d" : "?"	} ],
+	#     "meta" : {	"user_id" : 52933..., "start_ts" : 1422310693931,	"end_ts" : 1422310693931 },
+	#     "v" : 17082
+	#   }
+	#
+	#  and a pack looks like this
+	#
+	#   {
+	#     "doc_id" : 549dae9e0a2a615c0c7f0c98,
+	#     "project_id" : 549dae9c0a2a615c0c7f0c8c,
+	#     "pack" : [ D1, D2, D3, ....],
+	#     "meta" : {	"user_id" : 52933..., "start_ts" : 1422310693931,	"end_ts" : 1422310693931 },
+	#     "v" : 17082
+	#   }
+	#
+	#  where D1, D2, D3, .... are single updates stripped of their
+	#  doc_id and project_id fields (which are the same for all the
+	#  updates in the pack).  The meta and v fields of the pack itself
+	#  are those of the first entry in the pack D1 (this makes it
+	#  possible to treat packs and single updates in the same way).
+
 	_findResults: (param, query, limit, callback) ->
+		# param - the field used to select and sort ops within a range,
+		# either 'v' or 'meta.end_ts'
+		# query - the mongo query selector, includes both the doc_id/project_id and
+		# the range on v or meta.end_ts
+		# limit - the mongo limit, we need to apply it after unpacking any
+		# packs
+
 		sort = {}
 		sort[param] = -1;
 		cursor = db.docHistory
 			.find( query )
 			.sort( sort )
-
+		# if we have packs, we will trim the results more later after expanding them
 		if limit?
 			cursor.limit(limit)
 
+		# take the part of the query which selects the range over the parameter
 		rangeQuery = query[param]
+
+		# helper function to check if an item from a pack is inside the
+		# desired range
+		filterFn = (item) ->
+			return false if rangeQuery?['$gte']? && item[param] < rangeQuery['$gte']
+			return false if rangeQuery?['$lte']? && item[param] > rangeQuery['$lte']
+			return false if rangeQuery?['$lt']? && item[param] >= rangeQuery['$lt']
+			return false if rangeQuery?['$gt']? && item[param] <= rangeQuery['$gt']
+			return true
+
+		# create a query which can be used to select the entries BEFORE
+		# the range because we sometimes need to find extra ones (when the
+		# boundary falls in the middle of a pack)
 		extraQuery = _.clone(query)
+		# The pack uses its first entry for its metadata and v, so the
+		# only queries where we might not get all the packs are those for
+		# $gt and $gte (i.e. we need to find packs which start before our
+		# range but end in it)
 		if rangeQuery?['$gte']?
 			extraQuery[param] = {'$lt' : rangeQuery['$gte']}
 		else if rangeQuery?['$gt']

		return result

	_explodePackToOps: (packObj) ->
		doc_id = packObj.doc_id
		project_id = packObj.project_id
		result = packObj.pack.map (item) ->

				callback err, updates

	_unpackResults: (updates) ->
		#	iterate over the updates, if there's a pack, expand it into ops and
		# insert it into the array at that point
		result = []
		updates.forEach (item) ->
			if item.pack?
				all = MongoManager._explodePackToOps item
