Adjust to have better output with jsdoc.

2 files changed, 212 insertions, 89 deletions

diff --git a/jarmon/externdoc.js b/jarmon/externdoc.js
new file mode 100644
index 0000000..55a1d39
--- /dev/null
+++ b/jarmon/externdoc.js
@@ -0,0 +1,46 @@
+/**
+ * @module jQuery
+ * @see http://api.jquery.com/
+ */
+/**
+ * @class jQuery~jQuery
+ * @see http://api.jquery.com/Types/#jQuery
+ */
+/**
+ * @class jQuery~Deferred
+ * @see http://api.jquery.com/category/deferred-object/
+ */
+
+/**
+ * @module javascriptRRD
+ * @see http://javascriptrrd.sourceforge.net/docs/javascriptrrd_v1.1.1/doc/lib/index.html
+ */
+/**
+ * @module javascriptRRD~binaryXHR
+ * @see http://javascriptrrd.sourceforge.net/docs/javascriptrrd_v1.1.1/doc/lib/binaryXHR_js.html
+ */
+/**
+ * @class javascriptRRD~binaryXHR~BinaryFile
+ * @see http://javascriptrrd.sourceforge.net/docs/javascriptrrd_v1.1.1/doc/lib/binaryXHR_js.html#BinaryFile
+ */
+/**
+ * @module javascriptRRD~rrdFile
+ * @see http://javascriptrrd.sourceforge.net/docs/javascriptrrd_v1.1.1/doc/lib/rrdFile_js.html
+ */
+/**
+ * @class javascriptRRD~rrdFile~RRDFile
+ * @see http://javascriptrrd.sourceforge.net/docs/javascriptrrd_v1.1.1/doc/lib/rrdFile_js.html#RRDFile
+ */
+
+/**
+ * @module flot
+ * @see https://github.com/flot/flot/blob/master/API.md
+ */
+/**
+ * @class flot~data
+ * @see https://github.com/flot/flot/blob/master/API.md#data-format
+ */ 
+/**
+ * @class flot~options
+ * @see https://github.com/flot/flot/blob/master/API.md#plot-options
+ */
diff --git a/jarmon/jarmon.js b/jarmon/jarmon.js
index 9eeb280..9ce3b89 100644
--- a/jarmon/jarmon.js
+++ b/jarmon/jarmon.js
@@ -9,19 +9,16 @@
  * - http://collectd.org/
  *
  * Requirements:
- * - javascriptrrd.rrdFile: http://javascriptrrd.sourceforge.net/docs/javascriptrrd_v1.1.1/doc/lib/rrdFile_js.html
- * - javascriptrrd.binaryXHR: http://javascriptrrd.sourceforge.net/docs/javascriptrrd_v1.1.1/doc/lib/binaryXHR_js.html
+ * - javascriptRRD~rrdFile: http://javascriptrrd.sourceforge.net/docs/javascriptrrd_v1.1.1/doc/lib/rrdFile_js.html
+ * - javascriptRRD~binaryXHR: http://javascriptrrd.sourceforge.net/docs/javascriptrrd_v1.1.1/doc/lib/binaryXHR_js.html
  * - jQuery: http://jquery.com/
  * - Flot: http://code.google.com/p/flot/
- *
- * @module jarmon
  */
 
 /**
  * A namespace for Jarmon
  *
- * @class jarmon
- * @static
+ * @namespace jarmon
  */
 if(typeof(jarmon) === 'undefined') {
     var jarmon = {};
@@ -30,10 +27,10 @@ if(typeof(jarmon) === 'undefined') {
 /**
  * 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
+ * @method
+ * @param url {string} The url of the object to be downloaded
+ * @return {jQuery~Deferred} A deferred which will callback with an
+ *      instance of javascriptRRD~binaryXHR~BinaryFile
  */
 jarmon.downloadBinary = function(url) {
     var d = jQuery.Deferred();
@@ -71,10 +68,10 @@ 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
+ * @method
+ * @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
+ * @return {string} The formatted datetime string
  **/
 jarmon.localTimeFormatter = function (v, axis) {
     // map of app. size of time units in milliseconds
@@ -125,14 +122,13 @@ jarmon.localTimeFormatter = function (v, axis) {
 
 
 /**
- * A wrapper around an instance of javascriptrrd.RRDFile which provides a
+ * A wrapper around an instance of javascriptRRD~rrdFile~RRDFile which provides a
  * convenient way to query the RRDFile based on time range, RRD data source (DS)
  * and RRD consolidation function (CF).
  *
- * @class jarmon.RrdQuery
  * @constructor
- * @param rrd {Object} A javascriptrrd.RRDFile
- * @param unit {String} The unit symbol for this data series
+ * @param rrd {javascriptRRD~rrdFile~RRDFile}
+ * @param unit {string} The unit symbol for this data series
  **/
 jarmon.RrdQuery = function(rrd, unit) {
     this.rrd = rrd;
@@ -140,19 +136,19 @@ jarmon.RrdQuery = function(rrd, 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.
+ * 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
+ * @method
+ * @param startTimeJs {number} start timestamp in microseconds
+ * @param endTimeJs {number} end timestamp in microseconds
+ * @param [dsId=0] {(string|number)} identifier of the RRD datasource
+ * @param [cfName="AVERAGE"] {string} The name of an RRD consolidation function
+ *      (CF) eg AVERAGE, MIN, MAX
+ * @param {function} [transformer=function(v){return v}] A callable which
+ *      performs a tranfsformation of the values returned from the RRD file.
+ * @return {flot~data} A Flot compatible data series
  *      eg label: '', data: [], unit: ''
  **/
 jarmon.RrdQuery.prototype.getData = function(startTimeJs, endTimeJs,
@@ -263,8 +259,8 @@ jarmon.RrdQuery.prototype.getData = function(startTimeJs, endTimeJs,
 /**
  * Return a list of RRD Data Source names
  *
- * @method getDSNames
- * @return {Array} An array of DS names.
+ * @method
+ * @return {Array.<string>} An array of DS names.
  **/
 jarmon.RrdQuery.prototype.getDSNames = function() {
     return this.rrd.getDSNames();
@@ -275,12 +271,12 @@ jarmon.RrdQuery.prototype.getDSNames = function() {
  * A wrapper around RrdQuery which provides asynchronous access to the data in a
  * remote RRD file.
  *
- * @class jarmon.RrdQueryRemote
  * @constructor
- * @param url {String} The url of a remote RRD file
- * @param unit {String} The unit suffix of this data eg 'bit/sec'
- * @param downloader {Function} A callable which returns a Deferred and calls
- *      back with a javascriptrrd.BinaryFile when it has downloaded.
+ * @param url {string} The url of a remote RRD file
+ * @param unit {string} The unit suffix of this data eg 'bit/sec'
+ * @param [downloader=jarmon.downloadBinary] {function} A callable which returns
+ *      a Deferred and calls back with a javascriptRRD~binaryXHR~BinaryFile when
+ *      it has downloaded.
  **/
 jarmon.RrdQueryRemote = function(url, unit, downloader) {
     this.url = url;
@@ -295,7 +291,17 @@ jarmon.RrdQueryRemote = function(url, unit, downloader) {
     this._download = null;
 };
 
-
+/**
+ * Asynchronously call a method on the underlying jarmon.RrdQuery.  Think of it
+ * as an async .apply().
+ *
+ * @method
+ * @private
+ * @param methodName {string}
+ * @param args {Array}
+ * @return {jQuery~Deferred} A Deferred that calls .methodName(args...) on the
+ *      underlying jarmon.RrdQuery.
+ */
 jarmon.RrdQueryRemote.prototype._callRemote = function(methodName, args) {
     // Download the rrd if there has never been a download and don't start
     // another download if one is already in progress.
@@ -337,15 +343,16 @@ 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.
+ * @method
+ * @param startTime {number} The start timestamp
+ * @param endTime {number} The end timestamp
+ * @param [dsId=0] {(string|number)} identifier of the RRD datasource (string or number)
+ * @param [cfName="AVERAGE"] {string} The name of an RRD consolidation function
+ *      (CF) eg AVERAGE, MIN, MAX
+ * @param {function} [transformer=function(v){return v}] A callable which
+ *      performs a tranfsformation of the values returned from the RRD file.
+ * @return {jQuery~Deferred} A Deferred which calls back with a flot data
+ *      series.
  **/
 jarmon.RrdQueryRemote.prototype.getData = function(startTime, endTime,
                                                    dsId, cfName, transformer) {
@@ -359,8 +366,8 @@ 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.
+ * @method
+ * @return {jquery~Deferred} A Deferred which calls back with an array of DS names.
  **/
 jarmon.RrdQueryRemote.prototype.getDSNames = function() {
     return this._callRemote('getDSNames');
@@ -371,10 +378,9 @@ jarmon.RrdQueryRemote.prototype.getDSNames = function() {
  * Wraps RrdQueryRemote to provide access to a different RRD DSs within a
  * single RrdDataSource.
  *
- * @class jarmon.RrdQueryDsProxy
  * @constructor
- * @param rrdQuery {Object} An RrdQueryRemote instance
- * @param dsId {Variant} identifier of the RRD datasource (string or number)
+ * @param rrdQuery {jarmon.RrdQueryRemote} An RrdQueryRemote instance
+ * @param dsId {(string|number)} identifier of the RRD datasource (string or number)
  **/
 jarmon.RrdQueryDsProxy = function(rrdQuery, dsId, transformer) {
     this.rrdQuery = rrdQuery;
@@ -386,10 +392,11 @@ jarmon.RrdQueryDsProxy = function(rrdQuery, dsId, 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.
+ * @method
+ * @param startTime {number} A unix timestamp marking the start time
+ * @param endTime {number} A unix timestamp marking the start time
+ * @return {jQuery~Deferred} A Deferred which calls back with a flot data
+ *      series.
  **/
 jarmon.RrdQueryDsProxy.prototype.getData = function(startTime, endTime) {
     return this.rrdQuery.getData(startTime, endTime, this.dsId, undefined, this.transformer);
@@ -399,12 +406,11 @@ jarmon.RrdQueryDsProxy.prototype.getData = function(startTime, endTime) {
 /**
  * A class for creating a Flot chart from a series of RRD Queries
  *
- * @class jarmon.Chart
  * @constructor
- * @param template {Object} A jQuery containing a single element into which the
- *      chart will be drawn
- * @param options {Object} Flot options which control how the chart should be
- *      drawn.
+ * @param template {jQuery~jQuery} A jQuery containing a single element into
+ *      which the chart will be drawn
+ * @param options {flot~options} Flot options which control how the chart should
+ *      be drawn.
  **/
 jarmon.Chart = function(template, recipe,  downloader) {
     this.template = template;
@@ -489,6 +495,9 @@ jarmon.Chart = function(template, recipe,  downloader) {
     };
 };
 
+/**
+ * @method
+ */
 jarmon.Chart.prototype.setup = function() {
     this.template.find('.title').text(this.recipe.title);
     this.data = [];
@@ -518,11 +527,11 @@ 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,
+ * @method
+ * @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=true] {boolean} true if you want this data plotted on the chart,
  *      false if not.
  **/
 jarmon.Chart.prototype.addData = function(label, db, enabled) {
@@ -535,8 +544,8 @@ jarmon.Chart.prototype.addData = function(label, db, enabled) {
 /**
  * Enable / Disable a single data source
  *
- * @method switchDataEnabled
- * @param label {String} The label of the data source to be enabled /
+ * @method
+ * @param label {string} The label of the data source to be enabled /
  *      disabled.
  **/
 jarmon.Chart.prototype.switchDataEnabled = function(label) {
@@ -550,9 +559,10 @@ 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
+ * @method
+ * @param startTime {number} The start timestamp
+ * @param endTime {number} The end timestamp
+ * @return {Object} The same thing as .draw() returns
  **/
 jarmon.Chart.prototype.setTimeRange = function(startTime, endTime) {
     this.startTime = startTime;
@@ -565,9 +575,9 @@ jarmon.Chart.prototype.setTimeRange = function(startTime, endTime) {
  * 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.
+ * @method
+ * @return {jQuery~Deferred} A Deferred which calls back with the chart data
+ *      when the chart has been rendered.
  **/
 jarmon.Chart.prototype.draw = function() {
     var self = this;
@@ -692,8 +702,8 @@ jarmon.Chart.prototype.draw = function() {
 /**
  * Generate a form through which to choose a data source from a remote RRD file
  *
- * @class jarmon.RrdChooser
  * @constructor
+ * @param $tpl {jQuery~jQuery} jQuery object for the DOM node to attach to.
  **/
 jarmon.RrdChooser = function($tpl) {
     this.$tpl = $tpl;
@@ -705,6 +715,9 @@ jarmon.RrdChooser = function($tpl) {
     };
 };
 
+/**
+ * @method
+ */
 jarmon.RrdChooser.prototype.drawRrdUrlForm = function() {
     var self = this;
     this.$tpl.empty();
@@ -764,6 +777,9 @@ jarmon.RrdChooser.prototype.drawRrdUrlForm = function() {
     ).appendTo(this.$tpl);
 };
 
+/**
+ * @method
+ */
 jarmon.RrdChooser.prototype.drawDsLabelForm = function() {
     var self = this;
     this.$tpl.empty();
@@ -808,6 +824,9 @@ jarmon.RrdChooser.prototype.drawDsLabelForm = function() {
 };
 
 
+/**
+ * @method
+ */
 jarmon.RrdChooser.prototype.drawDsSummary = function() {
     var self = this;
     this.$tpl.empty();
@@ -830,6 +849,11 @@ jarmon.RrdChooser.prototype.drawDsSummary = function() {
 };
 
 
+/**
+ * @constructor
+ * @param $tpl {jQuery~jQuery}
+ * @param chart {jarmon.Chart}
+ */
 jarmon.ChartEditor = function($tpl, chart) {
     this.$tpl = $tpl;
     this.chart = chart;
@@ -887,6 +911,10 @@ jarmon.ChartEditor = function($tpl, chart) {
     );
 };
 
+
+/**
+ * @method
+ */
 jarmon.ChartEditor.prototype.draw = function() {
     var self = this;
     this.$tpl.empty();
@@ -950,6 +978,12 @@ jarmon.ChartEditor.prototype.draw = function() {
 };
 
 
+/**
+ * @method
+ * @private
+ * @param $row {jQuery~jQuery}
+ * @return {jQuery~jQuery}
+ */
 jarmon.ChartEditor.prototype._extractRowValues = function($row) {
     return $row.find('input[type=text]').map(
         function(i, el) {
@@ -959,6 +993,11 @@ jarmon.ChartEditor.prototype._extractRowValues = function($row) {
 };
 
 
+/**
+ * @method
+ * @private
+ * @param record {Array}
+ */
 jarmon.ChartEditor.prototype._addDatasourceRow = function(record) {
     $('<tr/>').append(
         $('<td/>').append(
@@ -984,6 +1023,11 @@ jarmon.ChartEditor.prototype._addDatasourceRow = function(record) {
 };
 
 
+/**
+ * @constructor
+ * @param $tpl {jQuery~jQuery}
+ * @param recipe {Array}
+ */
 jarmon.TabbedInterface = function($tpl, recipe) {
     this.$tpl = $tpl;
     this.recipe = recipe;
@@ -1007,6 +1051,11 @@ jarmon.TabbedInterface = function($tpl, recipe) {
     this.setup();
 };
 
+/**
+ * @method
+ * @param tabName {string}
+ * @return {jQuery~jQuery}
+ */
 jarmon.TabbedInterface.prototype.newTab = function(tabName) {
     // Add a tab
     $('<li/>').append(
@@ -1019,6 +1068,9 @@ jarmon.TabbedInterface.prototype.newTab = function(tabName) {
     return $placeholder;
 };
 
+/**
+ * @method
+ */
 jarmon.TabbedInterface.prototype.setup = function() {
     // Destroy then re-initialise the jquerytools tabs plugin
     var api = this.$tabBar.data("tabs");
@@ -1030,6 +1082,14 @@ jarmon.TabbedInterface.prototype.setup = function() {
 
 /**
  * Setup chart date range controls and all charts
+ *
+ * @method
+ * @param $chartTemplate {jQuery~jQuery}
+ * @param chartRecipes {Object}
+ * @param $tabTemplate {jQuery~jQuery}
+ * @param tabRecipes {Object}
+ * @param $controlPanelTemplate {jQuery~jQuery}
+ * @return {Array.<Array.<jarmon.Chart>, jarmon.TabbedInterface, jarmon.ChartCoordinator>}
  **/
 jarmon.buildTabbedChartUi = function ($chartTemplate, chartRecipes,
                                       $tabTemplate, tabRecipes,
@@ -1097,7 +1157,12 @@ jarmon.buildTabbedChartUi = function ($chartTemplate, chartRecipes,
 };
 
 
-// Options common to all the chart on this page
+/**
+ * Options common to all the chart on this page
+ *
+ * @static
+ * @default
+ */
 jarmon.Chart.BASE_OPTIONS = {
     grid: {
         clickable: false,
@@ -1130,7 +1195,12 @@ jarmon.Chart.BASE_OPTIONS = {
     }
 };
 
-// Extra options to generate a stacked chart
+/**
+ * Extra options to generate a stacked chart
+ *
+ * @static
+ * @default
+ */
 jarmon.Chart.STACKED_OPTIONS = {
     series: {
         stack: true,
@@ -1141,7 +1211,11 @@ jarmon.Chart.STACKED_OPTIONS = {
 };
 
 
-// A selection of useful time ranges
+/**
+ * A selection of useful time ranges
+ *
+ * @member
+ */
 jarmon.timeRangeShortcuts = [
     ['last hour', function(now) { return [now-60*60*1000*1, now]; }],
     ['last 3 hours', function(now) { return [now-60*60*1000*3, now]; }],
@@ -1158,9 +1232,8 @@ jarmon.timeRangeShortcuts = [
  * Presents the user with a form and a timeline with which they can choose a
  * time range and co-ordinates the refreshing of a series of charts.
  *
- * @class jarmon.ChartCoordinator
  * @constructor
- * @param ui {Object} A one element jQuery containing an input form and
+ * @param ui {jQuery~jQuery} A one element jQuery containing an input form and
  *      placeholders for the timeline and for the series of charts.
  **/
 jarmon.ChartCoordinator = function(ui, charts) {
@@ -1379,7 +1452,8 @@ 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
+ * @method
+ * @return {jQuery~Deferred}
  **/
 jarmon.ChartCoordinator.prototype.update = function() {
     var self = this;
@@ -1475,9 +1549,9 @@ 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
+ * @method
+ * @param [startTime=] {number} The start timestamp
+ * @param [endTime=] {number} The end timestamp
  **/
 jarmon.ChartCoordinator.prototype.setTimeRange = function(from, to) {
     if(typeof(from) !== 'undefined' && from !== null) {
@@ -1491,7 +1565,7 @@ jarmon.ChartCoordinator.prototype.setTimeRange = function(from, to) {
 /**
  * Reset all charts and the input form to the default time range - last hour
  *
- * @method init
+ * @method
  **/
 jarmon.ChartCoordinator.prototype.init = function() {
     this.update();
@@ -1500,9 +1574,8 @@ jarmon.ChartCoordinator.prototype.init = function() {
 /**
  * Limit the number of parallel async calls
  *
- * @class jarmon.Parallimiter
  * @constructor
- * @param limit {Number} The maximum number of in progress calls
+ * @param limit {number} The maximum number of in progress calls
  **/
 jarmon.Parallimiter = function(limit) {
     this.limit = limit || 1;
@@ -1514,10 +1587,10 @@ jarmon.Parallimiter = function(limit) {
  * 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.
+ * @method
+ * @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
+ * @return {jQuery~jQuery} A Deferred which fires with the result of the callable
  *       when it is called.
  **/
 jarmon.Parallimiter.prototype.addCallable = function(callable, args) {
@@ -1527,6 +1600,10 @@ jarmon.Parallimiter.prototype.addCallable = function(callable, args) {
     return d;
 };
 
+/**
+ * @method
+ * @private
+ */
 jarmon.Parallimiter.prototype._nextCall = function() {
     var self = this;
     if(this._callQueue.length > 0) {