[Telemetry] Add JSDoc

Add JSDoc and in-line comments to scripts in the
platform/telemetry bundle, for WTD-575.

platform/telemetry/src/TelemetryCapability.js

@@ -9,6 +9,9 @@ define(
         "use strict";
 
         /**
+         * A telemetry capability provides a means of requesting telemetry
+         * for a specific object, and for unwrapping the response (to get
+         * at the specific data which is appropriate to the domain object.)
          *
          * @constructor
          */
@@ -23,6 +26,8 @@ define(
                         telemetryService =
                             $q.when($injector.get("telemetryService"));
                     } catch (e) {
+                        // $injector should throw is telemetryService
+                        // is unavailable or unsatisfiable.
                         $log.warn("Telemetry service unavailable");
                         telemetryService = $q.reject(e);
                     }
@@ -30,21 +35,30 @@ define(
                 return telemetryService;
             }
 
+            // Build a request object. This takes the request that was
+            // passed to the capability, and adds source, id, and key
+            // fields associated with the object (from its type definition
+            // and/or its model)
             function buildRequest(request) {
+                // Start with any "telemetry" field in type; use that as a
+                // basis for the request.
                 var type = domainObject.getCapability("type"),
                     typeRequest = (type && type.getDefinition().telemetry) || {},
                     modelTelemetry = domainObject.getModel().telemetry,
                     fullRequest = Object.create(typeRequest);
 
+                // Add properties from the telemetry field of this
+                // specific domain object.
                 Object.keys(modelTelemetry).forEach(function (k) {
                     fullRequest[k] = modelTelemetry[k];
                 });
 
+                // Add properties from this specific requestData call.
                 Object.keys(request).forEach(function (k) {
                     fullRequest[k] = request[k];
                 });
 
-                // Include domain object ID, at minimum
+                // Ensure an ID and key are present
                 if (!fullRequest.id) {
                     fullRequest.id = domainObject.getId();
                 }
@@ -55,37 +69,63 @@ define(
                 return fullRequest;
             }
 
+            // Issue a request for telemetry data
             function requestTelemetry(request) {
                 // Bring in any defaults from the object model
                 var fullRequest = buildRequest(request || {}),
                     source = fullRequest.source,
                     key = fullRequest.key;
 
+                // Pull out the relevant field from the larger,
+                // structured response.
                 function getRelevantResponse(response) {
                     return ((response || {})[source] || {})[key] || {};
                 }
 
+                // Issue a request to the service
                 function requestTelemetryFromService(telemetryService) {
                     return telemetryService.requestTelemetry([fullRequest]);
                 }
 
+                // If a telemetryService is not available,
+                // getTelemetryService() should reject, and this should
+                // bubble through subsequent then calls.
                 return getTelemetryService()
                         .then(requestTelemetryFromService)
                         .then(getRelevantResponse);
             }
 
             return {
+                /**
+                 * Request telemetry data for this specific domain object.
+                 * @param {TelemetryRequest} [request] parameters for this
+                 *        specific request
+                 * @returns {Promise} a promise for the resulting telemetry
+                 *          object
+                 */
                 requestData: requestTelemetry,
+
+                /**
+                 * Get metadata about this domain object's associated
+                 * telemetry.
+                 */
                 getMetadata: function () {
+                    // metadata just looks like a request,
+                    // so use buildRequest to bring in both
+                    // type-level and object-level telemetry
+                    // properties
                     return buildRequest({});
                 }
             };
         }
 
+        /**
+         * The telemetry capability is applicable when a
+         * domain object model has a "telemetry" field.
+         */
         TelemetryCapability.appliesTo = function (model) {
             return (model &&
-                    model.telemetry &&
-                    model.telemetry.source) ? true : false;
+                    model.telemetry) ? true : false;
         };
 
         return TelemetryCapability;