Bug 723181: add some comments to TelemetryTimestamps, r=mak

--HG--
extra : transplant_source : z%AF9MyF%E6y%16%DAq%170%B7%5D6%DFgE%01

browser/modules/TelemetryTimestamps.jsm

@@ -4,8 +4,27 @@
 
 let EXPORTED_SYMBOLS = ["TelemetryTimestamps"];
 
+/**
+ * This module's purpose is to collect timestamps for important
+ * application-specific events.
+ *
+ * The TelemetryPing component attaches the timestamps stored by this module to
+ * the telemetry submission, substracting the process lifetime so that the times
+ * are relative to process startup. The overall goal is to produce a basic
+ * timeline of the startup process.
+ */
+let timeStamps = {};
+
 let TelemetryTimestamps = {
-  timeStamps: {},
+  /**
+   * Adds a timestamp to the list. The addition of TimeStamps that already have
+   * a value stored is ignored.
+   *
+   * @param name must be a unique, generally "camelCase" descriptor of what the
+   *             timestamp represents. e.g.: "delayedStartupStarted"
+   * @param value is a timeStamp in milliseconds since the epoch. If omitted,
+   *              defaults to Date.now().
+   */
   add: function TT_add(name, value) {
     // Default to "now" if not specified
     if (value == null)
@@ -15,12 +34,19 @@ let TelemetryTimestamps = {
       throw new Error("Value must be a timestamp");
 
     // If there's an existing value, just ignore the new value.
-    if (this.timeStamps.hasOwnProperty(name))
+    if (timeStamps.hasOwnProperty(name))
       return;
 
-    this.timeStamps[name] = value;
+    timeStamps[name] = value;
   },
+
+  /**
+   * Returns a JS object containing all of the timeStamps as properties (can be
+   * easily serialized to JSON). Used by TelemetryPing to retrieve the data
+   * to attach to the telemetry submission.
+   */
   get: function TT_get() {
-    return JSON.parse(JSON.stringify(this.timeStamps));
+    // Return a copy of the object by passing it through JSON.
+    return JSON.parse(JSON.stringify(timeStamps));
   }
 };