Hoist doc-comments out of functions.

2 files changed, 195 insertions, 196 deletions

diff --git a/jarmon/jarmon.js b/jarmon/jarmon.js
index 8594fda..9eeb280 100644
--- a/jarmon/jarmon.js
+++ b/jarmon/jarmon.js
@@ -27,15 +27,15 @@ if(typeof(jarmon) === 'undefined') {
     var jarmon = {};
 }
 
+/**
+ * Download a binary file asynchronously using the jQuery.ajax function
+ *
+ * @method downloadBinary
+ * @param url {String} The url of the object to be downloaded
+ * @return {Object} A deferred which will callback with an instance of
+ * javascriptrrd.BinaryFile
+ */
 jarmon.downloadBinary = function(url) {
-    /**
-     * Download a binary file asynchronously using the jQuery.ajax function
-     *
-     * @method downloadBinary
-     * @param url {String} The url of the object to be downloaded
-     * @return {Object} A deferred which will callback with an instance of
-     * javascriptrrd.BinaryFile
-     */
     var d = jQuery.Deferred();
     $.ajax({
         url: url,
@@ -67,16 +67,16 @@ jarmon.downloadBinary = function(url) {
 };
 
 
+/**
+ * Copied from jquery.flot.js and modified to allow timezone
+ * adjustment.
+ *
+ * @method localTimeFormatter
+ * @param v {Number} The timestamp to be formatted
+ * @param axis {Object} A hash containing information about the time axis
+ * @return {String} The formatted datetime string
+ **/
 jarmon.localTimeFormatter = function (v, axis) {
-    /**
-     * Copied from jquery.flot.js and modified to allow timezone
-     * adjustment.
-     *
-     * @method localTimeFormatter
-     * @param v {Number} The timestamp to be formatted
-     * @param axis {Object} A hash containing information about the time axis
-     * @return {String} The formatted datetime string
-     **/
     // map of app. size of time units in milliseconds
     var timeUnitSize = {
         "second": 1000,
@@ -139,25 +139,24 @@ jarmon.RrdQuery = function(rrd, unit) {
     this.unit = unit;
 };
 
+/**
+ * Generate a Flot compatible data object containing rows between start and
+ * end time. The rows are taken from the first RRA whose data spans the
+ * requested time range.
+ *
+ * @method getData
+ * @param startTimeJs {Number} start timestamp in microseconds
+ * @param endTimeJs {Number} end timestamp in microseconds
+ * @param dsId {Variant} identifier of the RRD datasource (string or number)
+ * @param cfName {String} The name of an RRD consolidation function (CF)
+ *      eg AVERAGE, MIN, MAX
+ * @param transformer {Function} A callable which performs a
+ *      tranfsformation of the values returned from the RRD file.
+ * @return {Object} A Flot compatible data series
+ *      eg label: '', data: [], unit: ''
+ **/
 jarmon.RrdQuery.prototype.getData = function(startTimeJs, endTimeJs,
                                              dsId, cfName, transformer) {
-    /**
-     * Generate a Flot compatible data object containing rows between start and
-     * end time. The rows are taken from the first RRA whose data spans the
-     * requested time range.
-     *
-     * @method getData
-     * @param startTimeJs {Number} start timestamp in microseconds
-     * @param endTimeJs {Number} end timestamp in microseconds
-     * @param dsId {Variant} identifier of the RRD datasource (string or number)
-     * @param cfName {String} The name of an RRD consolidation function (CF)
-     *      eg AVERAGE, MIN, MAX
-     * @param transformer {Function} A callable which performs a
-     *      tranfsformation of the values returned from the RRD file.
-     * @return {Object} A Flot compatible data series
-     *      eg label: '', data: [], unit: ''
-     **/
-
     if (startTimeJs >= endTimeJs) {
         throw RangeError(
             ['starttime must be less than endtime.',
@@ -261,13 +260,13 @@ jarmon.RrdQuery.prototype.getData = function(startTimeJs, endTimeJs,
 };
 
 
+/**
+ * Return a list of RRD Data Source names
+ *
+ * @method getDSNames
+ * @return {Array} An array of DS names.
+ **/
 jarmon.RrdQuery.prototype.getDSNames = function() {
-    /**
-     * Return a list of RRD Data Source names
-     *
-     * @method getDSNames
-     * @return {Array} An array of DS names.
-     **/
     return this.rrd.getDSNames();
 };
 
@@ -335,21 +334,21 @@ jarmon.RrdQueryRemote.prototype._callRemote = function(methodName, args) {
 };
 
 
+/**
+ * Return a Flot compatible data series asynchronously.
+ *
+ * @method getData
+ * @param startTime {Number} The start timestamp
+ * @param endTime {Number} The end timestamp
+ * @param dsId {Variant} identifier of the RRD datasource (string or number)
+ * @param cfName {String} The name of an RRD consolidation function (CF)
+ *      eg AVERAGE, MIN, MAX
+ * @param transformer {Function} A callable which performs a
+ *      tranfsformation of the values returned from the RRD file.
+ * @return {Object} A Deferred which calls back with a flot data series.
+ **/
 jarmon.RrdQueryRemote.prototype.getData = function(startTime, endTime,
                                                    dsId, cfName, transformer) {
-    /**
-     * Return a Flot compatible data series asynchronously.
-     *
-     * @method getData
-     * @param startTime {Number} The start timestamp
-     * @param endTime {Number} The end timestamp
-     * @param dsId {Variant} identifier of the RRD datasource (string or number)
-     * @param cfName {String} The name of an RRD consolidation function (CF)
-     *      eg AVERAGE, MIN, MAX
-     * @param transformer {Function} A callable which performs a
-     *      tranfsformation of the values returned from the RRD file.
-     * @return {Object} A Deferred which calls back with a flot data series.
-     **/
     if(this.lastUpdate < endTime/1000) {
         this._download = null;
     }
@@ -357,13 +356,13 @@ jarmon.RrdQueryRemote.prototype.getData = function(startTime, endTime,
 };
 
 
+/**
+ * Return a list of RRD Data Source names
+ *
+ * @method getDSNames
+ * @return {Object} A Deferred which calls back with an array of DS names.
+ **/
 jarmon.RrdQueryRemote.prototype.getDSNames = function() {
-    /**
-     * Return a list of RRD Data Source names
-     *
-     * @method getDSNames
-     * @return {Object} A Deferred which calls back with an array of DS names.
-     **/
     return this._callRemote('getDSNames');
 };
 
@@ -384,15 +383,15 @@ jarmon.RrdQueryDsProxy = function(rrdQuery, dsId, transformer) {
     this.transformer = transformer;
 };
 
+/**
+ * Call I{RrdQueryRemote.getData} with a particular dsId
+ *
+ * @method getData
+ * @param startTime {Number} A unix timestamp marking the start time
+ * @param endTime {Number} A unix timestamp marking the start time
+ * @return {Object} A Deferred which calls back with a flot data series.
+ **/
 jarmon.RrdQueryDsProxy.prototype.getData = function(startTime, endTime) {
-    /**
-     * Call I{RrdQueryRemote.getData} with a particular dsId
-     *
-     * @method getData
-     * @param startTime {Number} A unix timestamp marking the start time
-     * @param endTime {Number} A unix timestamp marking the start time
-     * @return {Object} A Deferred which calls back with a flot data series.
-     **/
     return this.rrdQuery.getData(startTime, endTime, this.dsId, undefined, this.transformer);
 };
 
@@ -515,32 +514,32 @@ jarmon.Chart.prototype.setup = function() {
     }
 };
 
+/**
+ * Add details of a remote RRD data source whose data will be added to this
+ * chart.
+ *
+ * @method addData
+ * @param label {String} The label for this data which will be shown in the
+ *               chart legend
+ * @param db {String} The url of the remote RRD database
+ * @param enabled {Boolean} true if you want this data plotted on the chart,
+ *      false if not.
+ **/
 jarmon.Chart.prototype.addData = function(label, db, enabled) {
-    /**
-     * Add details of a remote RRD data source whose data will be added to this
-     * chart.
-     *
-     * @method addData
-     * @param label {String} The label for this data which will be shown in the
-     *               chart legend
-     * @param db {String} The url of the remote RRD database
-     * @param enabled {Boolean} true if you want this data plotted on the chart,
-     *      false if not.
-     **/
     if(typeof(enabled) === 'undefined') {
         enabled = true;
     }
     this.data.push([label, db, enabled]);
 };
 
+/**
+ * Enable / Disable a single data source
+ *
+ * @method switchDataEnabled
+ * @param label {String} The label of the data source to be enabled /
+ *      disabled.
+ **/
 jarmon.Chart.prototype.switchDataEnabled = function(label) {
-    /**
-     * Enable / Disable a single data source
-     *
-     * @method switchDataEnabled
-     * @param label {String} The label of the data source to be enabled /
-     *      disabled.
-     **/
     for(var i=0; i<this.data.length; i++) {
         if(this.data[i][0] === label) {
             this.data[i][2] = !this.data[i][2];
@@ -548,29 +547,29 @@ jarmon.Chart.prototype.switchDataEnabled = function(label) {
     }
 };
 
+/**
+ * Alter the time range of this chart and redraw
+ *
+ * @method setTimeRange
+ * @param startTime {Number} The start timestamp
+ * @param endTime {Number} The end timestamp
+ **/
 jarmon.Chart.prototype.setTimeRange = function(startTime, endTime) {
-    /**
-     * Alter the time range of this chart and redraw
-     *
-     * @method setTimeRange
-     * @param startTime {Number} The start timestamp
-     * @param endTime {Number} The end timestamp
-     **/
     this.startTime = startTime;
     this.endTime = endTime;
     return this.draw();
 };
 
+/**
+ * Draw the chart
+ * A 'chart_loading' event is triggered before the data is requested
+ * A 'chart_loaded' event is triggered when the chart has been drawn
+ *
+ * @method draw
+ * @return {Object} A Deferred which calls back with the chart data when
+ *      the chart has been rendered.
+ **/
 jarmon.Chart.prototype.draw = function() {
-    /**
-     * Draw the chart
-     * A 'chart_loading' event is triggered before the data is requested
-     * A 'chart_loaded' event is triggered when the chart has been drawn
-     *
-     * @method draw
-     * @return {Object} A Deferred which calls back with the chart data when
-     *      the chart has been rendered.
-     **/
     var self = this;
     this.template.addClass('loading');
 
@@ -1029,12 +1028,12 @@ jarmon.TabbedInterface.prototype.setup = function() {
     this.$tabBar.tabs(this.$tabPanels.children('div'), {history: true});
 };
 
+/**
+ * Setup chart date range controls and all charts
+ **/
 jarmon.buildTabbedChartUi = function ($chartTemplate, chartRecipes,
                                       $tabTemplate, tabRecipes,
                                       $controlPanelTemplate) {
-    /**
-     * Setup chart date range controls and all charts
-     **/
     var p = new jarmon.Parallimiter(2);
     function serialDownloader(url) {
         return p.addCallable(jarmon.downloadBinary, [url]);
@@ -1376,13 +1375,13 @@ jarmon.ChartCoordinator = function(ui, charts) {
 };
 
 
+/**
+ * Grab the start and end time from the ui form, highlight the range on the
+ * range timeline and set the time range of all the charts and redraw.
+ *
+ * @method update
+ **/
 jarmon.ChartCoordinator.prototype.update = function() {
-    /**
-     * Grab the start and end time from the ui form, highlight the range on the
-     * range timeline and set the time range of all the charts and redraw.
-     *
-     * @method update
-     **/
     var self = this;
     var selection = this.ui.find('[name="from_standard"]').val();
 
@@ -1473,14 +1472,14 @@ jarmon.ChartCoordinator.prototype.update = function() {
         });
 };
 
+/**
+ * Set the start and end time fields in the form and trigger an update
+ *
+ * @method setTimeRange
+ * @param startTime {Number} The start timestamp
+ * @param endTime {Number} The end timestamp
+ **/
 jarmon.ChartCoordinator.prototype.setTimeRange = function(from, to) {
-    /**
-     * Set the start and end time fields in the form and trigger an update
-     *
-     * @method setTimeRange
-     * @param startTime {Number} The start timestamp
-     * @param endTime {Number} The end timestamp
-     **/
     if(typeof(from) !== 'undefined' && from !== null) {
         this.ui.find('[name="from"]').val(from);
     }
@@ -1489,12 +1488,12 @@ jarmon.ChartCoordinator.prototype.setTimeRange = function(from, to) {
     }
 };
 
+/**
+ * Reset all charts and the input form to the default time range - last hour
+ *
+ * @method init
+ **/
 jarmon.ChartCoordinator.prototype.init = function() {
-    /**
-     * Reset all charts and the input form to the default time range - last hour
-     *
-     * @method init
-     **/
     this.update();
 };
 
@@ -1511,17 +1510,17 @@ jarmon.Parallimiter = function(limit) {
     this._currentCallCount = 0;
 };
 
+/**
+ * Add a function to be called when the number of in progress calls drops
+ * below the configured limit
+ *
+ * @method addCallable
+ * @param callable {Function} A function which returns a Deferred.
+ * @param args {Array} A list of arguments to pass to the callable
+ * @return {Object} A Deferred which fires with the result of the callable
+ *       when it is called.
+ **/
 jarmon.Parallimiter.prototype.addCallable = function(callable, args) {
-    /**
-    * Add a function to be called when the number of in progress calls drops
-    * below the configured limit
-    *
-    * @method addCallable
-    * @param callable {Function} A function which returns a Deferred.
-    * @param args {Array} A list of arguments to pass to the callable
-    * @return {Object} A Deferred which fires with the result of the callable
-    *       when it is called.
-    **/
     var d = new jQuery.Deferred();
     this._callQueue.unshift([d, callable, args]);
     this._nextCall();
diff --git a/jarmon/jarmon.test.js b/jarmon/jarmon.test.js
index 5a56d5a..0bccf9c 100644
--- a/jarmon/jarmon.test.js
+++ b/jarmon/jarmon.test.js
@@ -8,11 +8,11 @@ YUI({ logInclude: { TestRunner: true } }).use('console', 'test', function(Y) {
     Y.Test.Runner.add(new Y.Test.Case({
         name: "jarmon.downloadBinary",
 
+        /**
+         * When url cannot be found, the deferred should errback with status
+         * 404.
+         **/
         test_urlNotFound: function () {
-            /**
-             * When url cannot be found, the deferred should errback with status
-             * 404.
-             **/
             var self = this;
             var d = new jarmon.downloadBinary('non-existent-file.html');
             d.always(
@@ -26,11 +26,11 @@ YUI({ logInclude: { TestRunner: true } }).use('console', 'test', function(Y) {
             this.wait();
         },
 
+        /**
+         * When url is found, the deferred should callback with an instance
+         * of javascriptrrd.BinaryFile
+         **/
         test_urlFound: function () {
-            /**
-             * When url is found, the deferred should callback with an instance
-             * of javascriptrrd.BinaryFile
-             **/
             var self = this;
             var d = new jarmon.downloadBinary('testfile.bin');
             d.always(
@@ -69,11 +69,11 @@ YUI({ logInclude: { TestRunner: true } }).use('console', 'test', function(Y) {
                 });
         },
 
+        /**
+         * The generated rrd file should have a lastupdate date of
+         * 1980-01-01 00:50:01
+         **/
         test_getLastUpdate: function () {
-            /**
-             * The generated rrd file should have a lastupdate date of
-             * 1980-01-01 00:50:01
-             **/
             var self = this;
             this.d.done(
                 function(rrd) {
@@ -85,12 +85,12 @@ YUI({ logInclude: { TestRunner: true } }).use('console', 'test', function(Y) {
             this.wait();
         },
 
+        /**
+         * The generated rrd file should have a single DS whose name is
+         * 'speed'. A RangeError is thrown if the requested index or dsName
+         * doesnt exist.
+         **/
         test_getDSIndex: function () {
-            /**
-             * The generated rrd file should have a single DS whose name is
-             * 'speed'. A RangeError is thrown if the requested index or dsName
-             * doesnt exist.
-             **/
             var self = this;
             this.d.done(
                 function(rrd) {
@@ -110,10 +110,10 @@ YUI({ logInclude: { TestRunner: true } }).use('console', 'test', function(Y) {
             this.wait();
         },
 
+        /**
+         * The generated rrd file should have a single RRA
+         **/
         test_getNrRRAs: function () {
-            /**
-             * The generated rrd file should have a single RRA
-             **/
             var self = this;
             this.d.done(
                 function(rrd) {
@@ -124,13 +124,13 @@ YUI({ logInclude: { TestRunner: true } }).use('console', 'test', function(Y) {
             this.wait();
         },
 
+        /**
+         * The generated rrd file should have a single RRA using AVERAGE
+         * consolidation, step=10, rows=6 and values 0-5
+         * rra.getEl throws a RangeError if asked for row which doesn't
+         * exist.
+         **/
         test_getRRA: function () {
-            /**
-             * The generated rrd file should have a single RRA using AVERAGE
-             * consolidation, step=10, rows=6 and values 0-5
-             * rra.getEl throws a RangeError if asked for row which doesn't
-             * exist.
-             **/
             var self = this;
             this.d.done(
                 function(rrd) {
@@ -168,10 +168,10 @@ YUI({ logInclude: { TestRunner: true } }).use('console', 'test', function(Y) {
                 });
         },
 
+        /**
+         * The starttime must be less than the endtime
+         **/
         test_getDataTimeRangeOverlapError: function () {
-            /**
-             * The starttime must be less than the endtime
-             **/
             var self = this;
             this.d.done(
                 function(rrd) {
@@ -191,11 +191,11 @@ YUI({ logInclude: { TestRunner: true } }).use('console', 'test', function(Y) {
         },
 
 
+        /**
+         * Error is raised if the rrd file doesn't contain an RRA with the
+         * requested consolidation function (CF)
+         **/
         test_getDataUnknownCfError: function () {
-            /**
-             * Error is raised if the rrd file doesn't contain an RRA with the
-             * requested consolidation function (CF)
-             **/
             var self = this;
             this.d.done(
                 function(rrd) {
@@ -214,13 +214,13 @@ YUI({ logInclude: { TestRunner: true } }).use('console', 'test', function(Y) {
         },
 
 
+        /**
+         * The generated rrd file should have values 0-9 at 300s intervals
+         * starting at 1980-01-01 00:00:00
+         * Result should include a data points with times > starttime and
+         * <= endTime
+         **/
         test_getData: function () {
-            /**
-             * The generated rrd file should have values 0-9 at 300s intervals
-             * starting at 1980-01-01 00:00:00
-             * Result should include a data points with times > starttime and
-             * <= endTime
-             **/
             var self = this;
             this.d.done(
                 function(rrd) {
@@ -266,11 +266,11 @@ YUI({ logInclude: { TestRunner: true } }).use('console', 'test', function(Y) {
             this.wait();
         },
 
+        /**
+         * If the requested time range is outside the range of the RRD file
+         * we should not get any values back
+         **/
         test_getDataUnknownValues: function () {
-            /**
-             * If the requested time range is outside the range of the RRD file
-             * we should not get any values back
-             **/
             var self = this;
             this.d.done(
                 function(rrd) {
@@ -287,11 +287,11 @@ YUI({ logInclude: { TestRunner: true } }).use('console', 'test', function(Y) {
             return v * 10;
         },
 
+        /**
+         * RrdQuery can be passed a transformer function which may
+         * manipulate the values from the RRDFile
+         **/
         test_transformerFunction: function () {
-            /**
-             * RrdQuery can be passed a transformer function which may
-             * manipulate the values from the RRDFile
-             **/
             var self = this;
             this.d.done(
                 function(rrd) {
@@ -318,10 +318,10 @@ YUI({ logInclude: { TestRunner: true } }).use('console', 'test', function(Y) {
             this.rq = new jarmon.RrdQueryRemote('build/test.rrd', '');
         },
 
+        /**
+         * The starttime must be less than the endtime
+         **/
         test_getDataTimeRangeOverlapError: function () {
-            /**
-             * The starttime must be less than the endtime
-             **/
             var self = this;
             this.rq.getData(1, 0).fail(
                 function(res) {
@@ -333,11 +333,11 @@ YUI({ logInclude: { TestRunner: true } }).use('console', 'test', function(Y) {
         },
 
 
+        /**
+         * Error is raised if the rrd file doesn't contain an RRA with the
+         * requested consolidation function (CF)
+         **/
         test_getDataUnknownCfError: function () {
-            /**
-             * Error is raised if the rrd file doesn't contain an RRA with the
-             * requested consolidation function (CF)
-             **/
             var self = this;
             this.rq.getData(RRD_STARTTIME, RRD_ENDTIME, 0, 'FOO').always(
                 function(res) {
@@ -349,13 +349,13 @@ YUI({ logInclude: { TestRunner: true } }).use('console', 'test', function(Y) {
         },
 
 
+        /**
+         * The generated rrd file should have values 0-9 at 300s intervals
+         * starting at 1980-01-01 00:00:00
+         * Result should include a data points with times > starttime and
+         * <= endTime
+         **/
         test_getData: function () {
-            /**
-             * The generated rrd file should have values 0-9 at 300s intervals
-             * starting at 1980-01-01 00:00:00
-             * Result should include a data points with times > starttime and
-             * <= endTime
-             **/
             var self = this;
             this.rq.getData(RRD_STARTTIME + (RRD_STEP+1) * 1000,
                             RRD_ENDTIME - (RRD_STEP-1) * 1000).always(
@@ -396,11 +396,11 @@ YUI({ logInclude: { TestRunner: true } }).use('console', 'test', function(Y) {
             this.wait();
         },
 
+        /**
+         * If the requested time range is outside the range of the RRD file
+         * we should not get any values back
+         **/
         test_getDataUnknownValues: function () {
-            /**
-             * If the requested time range is outside the range of the RRD file
-             * we should not get any values back
-             **/
             var self = this;
             this.rq.getData(RRD_ENDTIME, RRD_ENDTIME+1000).always(
                 function(data) {