From 142af3db777bdfae9fef3bb89cc3aed2e74d9295 Mon Sep 17 00:00:00 2001 From: Victor Woeltjen Date: Fri, 4 Sep 2015 15:44:18 -0700 Subject: [PATCH] [Time Controller] Add JSDoc WTD-1515 --- .../src/ConductorCapabilityDecorator.js | 11 +++++ .../conductor/src/ConductorRepresenter.js | 8 +++- .../conductor/src/ConductorService.js | 15 +++++++ .../src/ConductorTelemetryCapability.js | 13 ++++++ .../features/conductor/src/TimeConductor.js | 45 +++++++++++++++++++ 5 files changed, 91 insertions(+), 1 deletion(-) diff --git a/platform/features/conductor/src/ConductorCapabilityDecorator.js b/platform/features/conductor/src/ConductorCapabilityDecorator.js index 85b34152f3..7c6ba46133 100644 --- a/platform/features/conductor/src/ConductorCapabilityDecorator.js +++ b/platform/features/conductor/src/ConductorCapabilityDecorator.js @@ -26,6 +26,17 @@ define( function (ConductorTelemetryCapability) { 'use strict'; + /** + * Decorates the `capabilityService` such that any exposed `telemetry` + * capabilities have their requests mediated by the time conductor. + * + * @constructor + * @memberof platform/features/conductor + * @implements {CapabilityService} + * @param {platform/features/conductor.ConductorService} conductorServe + * the service which exposes the global time conductor + * @param {CapabilityService} capabilityService the decorated service + */ function ConductorCapabilityDecorator(conductorService, capabilityService) { this.conductorService = conductorService; this.capabilityService = capabilityService; diff --git a/platform/features/conductor/src/ConductorRepresenter.js b/platform/features/conductor/src/ConductorRepresenter.js index f0a32c69a0..0617c771b1 100644 --- a/platform/features/conductor/src/ConductorRepresenter.js +++ b/platform/features/conductor/src/ConductorRepresenter.js @@ -42,9 +42,15 @@ define( * The ConductorRepresenter attaches the universal time conductor * to views. * - * @memberof platform/commonUI/edit * @implements {Representer} * @constructor + * @memberof platform/features/conductor + * @param {platform/features/conductor.ConductorService} conductorService + * service which provides the active time conductor + * @param $compile Angular's $compile + * @param {ViewDefinition[]} views all defined views + * @param {Scope} the scope of the representation + * @param element the jqLite-wrapped representation element */ function ConductorRepresenter(conductorService, $compile, views, scope, element) { var conductorScope; diff --git a/platform/features/conductor/src/ConductorService.js b/platform/features/conductor/src/ConductorService.js index c40838ff53..59cfa95e3c 100644 --- a/platform/features/conductor/src/ConductorService.js +++ b/platform/features/conductor/src/ConductorService.js @@ -29,6 +29,16 @@ define( var ONE_DAY_IN_MS = 1000 * 60 * 60 * 24, SIX_HOURS_IN_MS = ONE_DAY_IN_MS / 4; + /** + * Provides a single global instance of the time conductor, which + * controls both query ranges and displayed ranges for telemetry + * data. + * + * @constructor + * @memberof platform/features/conductor + * @param {Function} now a function which returns the current time + * as a UNIX timestamp, in milliseconds + */ function ConductorService(now) { var initialEnd = Math.ceil(now() / SIX_HOURS_IN_MS) * SIX_HOURS_IN_MS; @@ -37,6 +47,11 @@ define( new TimeConductor(initialEnd - ONE_DAY_IN_MS, initialEnd); } + /** + * Get the global instance of the time conductor. + * @returns {platform/features/conductor.TimeConductor} the + * time conductor + */ ConductorService.prototype.getConductor = function () { return this.conductor; }; diff --git a/platform/features/conductor/src/ConductorTelemetryCapability.js b/platform/features/conductor/src/ConductorTelemetryCapability.js index 02950ac8f2..5d224b0415 100644 --- a/platform/features/conductor/src/ConductorTelemetryCapability.js +++ b/platform/features/conductor/src/ConductorTelemetryCapability.js @@ -26,6 +26,19 @@ define( function () { 'use strict'; + /** + * Wrapper for the `telemetry` capability which adds start/end + * times to all requests based on the current state of a time + * conductor. + * + * @constructor + * @memberof platform/features/conductor + * @augments {platform/telemetry.TelemetryCapability} + * @param {platform/features/conductor.TimeConductor} timeConductor + * the time conductor which controls these queries + * @param {platform/telemetry.TelemetryCapability} telemetryCapability + * the wrapped capability + */ function ConductorTelemetryCapability(timeConductor, telemetryCapability) { this.timeConductor = timeConductor; this.wrappedCapability = telemetryCapability; diff --git a/platform/features/conductor/src/TimeConductor.js b/platform/features/conductor/src/TimeConductor.js index d4eefeffd8..eeb104839a 100644 --- a/platform/features/conductor/src/TimeConductor.js +++ b/platform/features/conductor/src/TimeConductor.js @@ -21,15 +21,44 @@ *****************************************************************************/ /*global define*/ +/** + * The time conductor bundle adds a global control to the bottom of the + * outermost viewing area. This controls both the range for time-based + * queries and for time-based displays. + * + * @namespace platform/features/conductor + */ define( function () { 'use strict'; + /** + * Wrapper for the `telemetry` capability which adds start/end + * times to all requests based on the current state of a time + * conductor. + * + * Note that both start and end times are in units which may + * vary depending on the domains of telemetry being used. Most + * commonly, these are UNIX timestamps in milliseconds. + * + * @memberof platform/features/conductor + * @constructor + * @augments {platform/telemetry.TelemetryCapability} + * @param {platform/features/conductor.TimeConductor} timeConductor + * the time conductor which controls these queries + * @param {platform/telemetry.TelemetryCapability} telemetryCapability + * the wrapped capability + */ function TimeConductor(start, end) { this.inner = [ start, end ]; this.outer = [ start, end ]; } + /** + * Get or set (if called with an argument) the start time for queries. + * @param {number} [value] the start time to set + * @returns {number} the start time + */ TimeConductor.prototype.queryStart = function (value) { if (arguments.length > 0) { this.outer[0] = value; @@ -37,6 +66,11 @@ define( return this.outer[0]; }; + /** + * Get or set (if called with an argument) the end time for queries. + * @param {number} [value] the end time to set + * @returns {number} the end time + */ TimeConductor.prototype.queryEnd = function (value) { if (arguments.length > 0) { this.outer[1] = value; @@ -44,6 +78,12 @@ define( return this.outer[1]; }; + + /** + * Get or set (if called with an argument) the start time for displays. + * @param {number} [value] the start time to set + * @returns {number} the start time + */ TimeConductor.prototype.displayStart = function (value) { if (arguments.length > 0) { this.inner[0] = value; @@ -51,6 +91,11 @@ define( return this.inner[0]; }; + /** + * Get or set (if called with an argument) the end time for displays. + * @param {number} [value] the end time to set + * @returns {number} the end time + */ TimeConductor.prototype.displayEnd = function (value) { if (arguments.length > 0) { this.inner[1] = value;