From c0fda5b5729116798392f7060fad7ad10b86bcc7 Mon Sep 17 00:00:00 2001
From: Victor Woeltjen <victor.woeltjen@nasa.gov>
Date: Thu, 22 Oct 2015 12:41:46 -0700
Subject: [PATCH] [Time Conductor] Add JSDoc

Add typedefs relevant to the date aggregator; in particular,
document properties used to determine how to format timestamps
associated with a telemetry point.
---
 .../general/src/services/DateAggregator.js    |  4 +-
 platform/telemetry/src/TelemetryCapability.js | 58 +++++++++++++++++++
 2 files changed, 61 insertions(+), 1 deletion(-)

diff --git a/platform/commonUI/general/src/services/DateAggregator.js b/platform/commonUI/general/src/services/DateAggregator.js
index 3c2762d1bd..ee01929b27 100644
--- a/platform/commonUI/general/src/services/DateAggregator.js
+++ b/platform/commonUI/general/src/services/DateAggregator.js
@@ -31,7 +31,9 @@ define([
      * Formats dates for display and parses dates from user input,
      * varying by a chosen time system.
      *
-     * Time systems are typically domain keys from telemetry metadata.
+     * Time systems are typically specified as `system` properties
+     * of domains in {@link TelemetryDomainMetadata}.
+     *
      * If omitted/left undefined, the time system is presumed to be UTC time,
      * with its numeric interpretation being milliseconds since the
      * start of 1970.
diff --git a/platform/telemetry/src/TelemetryCapability.js b/platform/telemetry/src/TelemetryCapability.js
index 1fbd12a691..d89b3cd3bf 100644
--- a/platform/telemetry/src/TelemetryCapability.js
+++ b/platform/telemetry/src/TelemetryCapability.js
@@ -36,6 +36,64 @@ define(
                 getRangeValue: ZERO
             };
 
+        /**
+         * Provides metadata about telemetry associated with a
+         * given domain object.
+         *
+         * @typedef TelemetryMetadata
+         * @property {string} source the machine-readable identifier for
+         *           the source of telemetry data for this object; used by
+         *           {@link TelemetryService} implementations to determine
+         *           whether or not they provide data for this object.
+         * @property {string} key the machine-readable identifier for
+         *           telemetry data associated with this specific object,
+         *           within that `source`.
+         * @property {TelemetryDomainMetadata[]} domains supported domain
+         *           options for telemetry data associated with this object,
+         *           to use in interpreting a {@link TelemetrySeries}
+         * @property {TelemetryRangeMetadata[]} ranges supported range
+         *           options for telemetry data associated with this object,
+         *           to use in interpreting a {@link TelemetrySeries}
+         */
+
+        /**
+         * Provides metadata about range options within a telemetry series.
+         * Range options describe distinct properties within any given datum
+         * of a telemetry series; for instance, a telemetry series containing
+         * both raw and uncalibrated values may provide separate ranges for
+         * each.
+         *
+         * @typedef TelemetryRangeMetadata
+         * @property {string} key machine-readable identifier for this range
+         * @property {string} name human-readable name for this range
+         * @property {string} [units] human-readable units for this range
+         * @property {string} [format] data format for this range; usually,
+         *                    one of `number`, or `string`. If `undefined`,
+         *                    should presume to be a `number`. Custom formats
+         *                    may be indicated here.
+         */
+
+        /**
+         * Provides metadata about domain options within a telemetry series.
+         * Domain options describe distinct properties within any given datum
+         * of a telemtry series; for instance, a telemetry series containing
+         * both spacecraft event time and earth received times may provide
+         * separate domains for each.
+         *
+         * Domains are typically used to represent timestamps in a telemetry
+         * series, but more generally may express any property which will
+         * have unique values for each datum in a series. It is this property
+         * which makes domains distinct from ranges, as it makes these values
+         * appropriate and meaningful for use to sort and bound a series.
+         *
+         * @typedef TelemetryDomainMetadata
+         * @property {string} key machine-readable identifier for this range
+         * @property {string} name human-readable name for this range
+         * @property {string} [system] machine-readable identifier for the
+         *                    time/date system associated with this domain;
+         *                    used by {@link DateService}
+         */
+
         /**
          * A telemetry capability provides a means of requesting telemetry
          * for a specific object, and for unwrapping the response (to get