[API] Telemetry registration example

API.md

@@ -152,6 +152,41 @@ openmct.composition.addProvider({
 });
 ```
 
+### Adding Telemetry Providers
+
+When connecting to a new telemetry source, you will want to register a new
+[telemetry provider]{@link module:openmct.TelemetryAPI~TelemetryProvider}
+with the [telemetry API]{@link module:openmct.TelemetryAPI#addProvider}:
+
+```
+openmct.telemetry.addProvider({
+    canProvideTelemetry: function (domainObject) {
+        return domainObject.type === 'my-type';
+    },
+    properties: function (domainObject) {
+        return [
+            { key: 'value', name: "Temperature", units: "degC" },
+            { key: 'time', name: "UTC" }
+        ];
+    },
+    request: function (domainObject, options) {
+        var telemetryId = domainObject.myTelemetryId;
+        return myAdapter.request(telemetryId, options.start, options.end);
+    },
+    subscribe: function (domainObject, callback) {
+        var telemetryId = domainObject.myTelemetryId;
+        myAdapter.subscribe(telemetryId, callback);
+        return myAdapter.unsubscribe.bind(myAdapter, telemetryId, callback);
+    }
+});
+```
+
+The implementations for `request` and `subscribe` can vary depending on the
+nature of the endpoint which will provide telemetry. In the example above,
+it is assumed that `myAdapter` contains the specific implementations
+(HTTP requests, WebSocket connections, etc.) associated with some telemetry
+source.
+
 ## Using Open MCT
 
 When implementing new features, it is useful and sometimes necessary to

src/api/telemetry/TelemetryAPI.js

@@ -61,7 +61,7 @@ define([
      * @property {string} key the name of the property in the datum which
      *           contains this telemetry value
      * @property {string} name the human-readable name for this property
-     * @property {string} units the units associated with this property
+     * @property {string} [units] the units associated with this property
      * @property {boolean} [temporal] true if this property is a timestamp, or
      *           may be otherwise used to order telemetry in a time-like
      *           fashion; default is false
@@ -295,7 +295,7 @@ define([
             /**
              * Register a telemetry provider with the telemetry service. This
              * allows you to connect alternative telemetry sources.
-             * @method registerProvider
+             * @method addProvider
              * @memberof module:openmct.TelemetryAPI#
              * @param {module:openmct.TelemetryAPI~TelemetryProvider} provider the new
              *        telemetry provider
@@ -304,7 +304,7 @@ define([
              *        default provider (when no strategy is requested or no
              *        matching strategy is found.)
              */
-            registerProvider: registerProvider,
+            addProvider: registerProvider,
 
             /**
              * Request historical telemetry for a domain object.
@@ -362,6 +362,11 @@ define([
              * interpret your telemetry data, and then they use the format API
              * to format that data for display.
              *
+             * This method is optional.
+             * If a provider does not implement this method, it is presumed
+             * that all telemetry associated with this domain object can
+             * be formatted correctly by string coercion.
+             *
              * @param {module:openmct.DomainObject} domainObject the domain
              *        object for which to format telemetry
              * @returns {module:openmct.TelemetryAPI~TelemetryFormatter}
@@ -382,6 +387,10 @@ define([
              * Get a limit evaluator for this domain object.
              * Limit Evaluators help you evaluate limit and alarm status of individual telemetry datums for display purposes without having to interact directly with the Limit API.
              *
+             * This method is optional.
+             * If a provider does not implement this method, it is presumed
+             * that no limits are defined for this domain object's telemetry.
+             *
              * @param {module:openmct.DomainObject} domainObject the domain
              *        object for which to evaluate limits
              * @returns {module:openmct.TelemetryAPI~LimitEvaluator}