Document the lookup table

src/scales/scale.time.js

@@ -50,19 +50,36 @@ module.exports = function(Chart) {
 		return a - b;
 	}
 
-	function buildLookupTable(ticks, min, max, linear) {
-		var ilen = ticks.length;
+	/**
+	 * Returns an array of {time, pos} objects used to interpolate a specific `time` or position
+	 * (`pos`) on the scale, by searching entries before and after the requested value. Since the
+	 * value is linearly interpolated, only timestamps that break the time linearity are added,
+	 * meaning that in the best case, it contains only 2 objects: {min, 0} and {max, 1}. `pos` is
+	 * a decimal between 0 and 1: 0 being the start of the scale (left or top) and 1 the other
+	 * extremity (left + width or top + height). Note that it would be more optimized to directly
+	 * store pre-computed pixels, but the scale dimensions are not guaranty at the time we need
+	 * to create the lookup table.
+	 *
+	 * @param {Number[]} timestamps - timestamps sorted from lowest to highest
+	 * @param {Boolean} linear - if true, `pos` will be calculated to maintain the time linearity
+	 * along the scale, else timestamps will be spread at the same distance form each other.
+	 */
+	function buildLookupTable(timestamps, linear) {
+		var ilen = timestamps.length;
 		var table = [];
-		var i, prev, curr, next, pos;
+		var min, max, i, prev, curr, next, pos;
 
 		if (ilen === 0) {
 			return table;
 		}
 
+		min = timestamps[0];
+		max = timestamps[ilen - 1];
+
 		for (i = 0; i<ilen; ++i) {
-			next = ticks[i + 1] || 0;
-			prev = ticks[i - 1] || 0;
-			curr = ticks[i];
+			next = timestamps[i + 1] || 0;
+			prev = timestamps[i - 1] || 0;
+			curr = timestamps[i];
 
 			// only add points that breaks the scale linearity
 			if (Math.round((next + prev) / 2) !== curr) {
@@ -240,14 +257,14 @@ module.exports = function(Chart) {
 			}
 
 			me.ticks = ticks;
-			me.min = min = ticks[0];
-			me.max = max = ticks[ticks.length - 1];
+			me.min = ticks[0];
+			me.max = ticks[ticks.length - 1];
 			me.unit = unit;
 			me.majorUnit = majorUnit;
 			me.displayFormat = formats[unit];
 			me.majorDisplayFormat = formats[majorUnit];
 
-			model.table = buildLookupTable(ticks, min, max, ticksOpts.mode === 'linear');
+			model.table = buildLookupTable(ticks, ticksOpts.mode === 'linear');
 		},
 
 		getLabelForIndex: function(index, datasetIndex) {