[Scrolling] Add JSDoc, clean up

Clean up scripts for Scrolling List view and add
some JSDoc. WTD-534.

platform/features/scrolling/src/DomainColumn.js

@@ -1,27 +1,45 @@
-/*global define,Promise*/
+/*global define,moment*/
 
 /**
  * Module defining DomainColumn. Created by vwoeltje on 11/18/14.
  */
 define(
-    [],
+    ["../../plot/lib/moment.min"],
     function () {
         "use strict";
 
+        // Date format to use for domain values; in particular,
+        // use day-of-year instead of month/day
+        var DATE_FORMAT = "YYYY-DDD HH:mm:ss";
+
         /**
+         * A column which will report telemetry domain values
+         * (typically, timestamps.) Used by the ScrollingListController.
          *
          * @constructor
+         * @param domainMetadata an object with the machine- and human-
+         *        readable names for this domain (in `key` and `name`
+         *        fields, respectively.)
          */
         function DomainColumn(domainMetadata) {
             return {
+                /**
+                 * Get the title to display in this column's header.
+                 * @returns {string} the title to display
+                 */
                 getTitle: function () {
                     return domainMetadata.name;
                 },
+                /**
+                 * Get the text to display inside a row under this
+                 * column.
+                 * @returns {string} the text to display
+                 */
                 getValue: function (domainObject, data, index) {
-                    return data.getDomainValue(
+                    return moment.utc(data.getDomainValue(
                         index,
                         domainMetadata.key
-                    );
+                    )).format(DATE_FORMAT);
                 }
             };
         }

platform/features/scrolling/src/NameColumn.js

@@ -9,14 +9,25 @@ define(
         "use strict";
 
         /**
+         * A column which will report the name of the domain object
+         * which exposed specific telemetry values.
          *
          * @constructor
          */
         function NameColumn() {
             return {
+                /**
+                 * Get the title to display in this column's header.
+                 * @returns {string} the title to display
+                 */
                 getTitle: function () {
                     return "Name";
                 },
+                /**
+                 * Get the text to display inside a row under this
+                 * column. This returns the domain object's name.
+                 * @returns {string} the text to display
+                 */
                 getValue: function (domainObject) {
                     return domainObject.getModel().name;
                 }

platform/features/scrolling/src/RangeColumn.js

@@ -9,19 +9,31 @@ define(
         "use strict";
 
         /**
+         * A column which will report telemetry range values
+         * (typically, measurements.) Used by the ScrollingListController.
          *
          * @constructor
+         * @param rangeMetadata an object with the machine- and human-
+         *        readable names for this range (in `key` and `name`
+         *        fields, respectively.)
          */
         function RangeColumn(rangeMetadata) {
             return {
+                /**
+                 * Get the title to display in this column's header.
+                 * @returns {string} the title to display
+                 */
                 getTitle: function () {
                     return rangeMetadata.name;
                 },
+                /**
+                 * Get the text to display inside a row under this
+                 * column.
+                 * @returns {string} the text to display
+                 */
                 getValue: function (domainObject, data, index) {
-                    return data.getRangeValue(
+                    var value = data.getRangeValue(index, rangeMetadata.key);
-                        index,
+                    return value && value.toFixed(3);
-                        rangeMetadata.key
-                    );
                 }
             };
         }

platform/features/scrolling/src/ScrollingListController.js

@@ -11,7 +11,8 @@ define(
         var ROW_COUNT = 18;
 
         /**
-         *
+         * The ScrollingListController is responsible for populating
+         * the contents of the scrolling list view.
          * @constructor
          */
         function ScrollingListController($scope) {
@@ -85,18 +86,25 @@ define(
                         // in the data set on the next iteration
                         used[candidate.objectIndex] = used[candidate.objectIndex] + 1;
                     } else {
-                        break; // Ran out of candidates; not enough data points available
+                        // Ran out of candidates; not enough data points
+                        // available to fill all rows.
+                        break;
                     }
                 }
 
                 return latest;
             }
 
+            // Get a set of populated, ready-to-display rows for the
+            // latest data values.
             function getRows(telemetry) {
                 var datas = telemetry.getResponse(),
                     objects = telemetry.getTelemetryObjects(),
                     values = getLatestDataValues(datas);
 
+                // Each value will become a row, which will contain
+                // some value in each column (rendering by the
+                // column object itself)
                 return values.map(function (value) {
                     return columns.map(function (column) {
                         return column.getValue(
@@ -108,17 +116,22 @@ define(
                 });
             }
 
+            // Update the contents
             function updateRows() {
                 var telemetry = $scope.telemetry;
                 $scope.rows = telemetry ? getRows(telemetry) : [];
             }
 
-            function setupColumns() {
+            // Set up columns based on telemetry metadata. This will
-                var telemetry = $scope.telemetry,
+            // include one column for each domain and range type, as
-                    domainKeys = {},
+            // well as a column for the domain object name.
+            function setupColumns(telemetry) {
+                var domainKeys = {},
                     rangeKeys = {},
                     metadata;
 
+                // Add a domain to the set of columns, if a domain
+                // with the same key has not yet been inclued.
                 function addDomain(domain) {
                     var key = domain.key;
                     if (key && !domainKeys[key]) {
@@ -126,6 +139,8 @@ define(
                     }
                 }
 
+                // Add a range to the set of columns, if a range
+                // with the same key has not yet been inclued.
                 function addRange(range) {
                     var key = range.key;
                     if (key && !rangeKeys[key]) {
@@ -133,6 +148,8 @@ define(
                     }
                 }
 
+                // We cannot proceed if the telemetry controller
+                // is not available; clear all rows/columns.
                 if (!telemetry) {
                     columns = [];
                     $scope.rows = [];
@@ -158,10 +175,13 @@ define(
                     columns.push(new RangeColumn({ name: "Value" }));
                 }
 
+                // We have all columns now, so populate the headers
+                // for these columns in the scope.
                 $scope.headers = columns.map(function (column) {
                     return column.getTitle();
                 });
 
+                // Fill in the contents of the rows.
                 updateRows();
             }