Fix doc strings for compatibility with yuidoc

1 files changed, 142 insertions, 99 deletions

diff --git a/jarmon.js b/jarmon.js
index 5ec5283..44c4dad 100644
--- a/jarmon.js
+++ b/jarmon.js
@@ -1,8 +1,9 @@
-/* Copyright (c) 2010 Richard Wall <richard (at) the-moon.net>
+/**
+ * Copyright (c) 2010 Richard Wall <richard (at) the-moon.net>
  * See LICENSE for details.
  *
  * Wrappers and convenience fuctions for working with the javascriptRRD, jQuery,
- * and flot charting packages.
+ * and Flot charting packages.
  *
  * Designed to work well with the RRD files generated by Collectd:
  * - http://collectd.org/
@@ -12,20 +13,29 @@
  * - jQuery: http://jquery.com/
  * - Flot: http://code.google.com/p/flot/
  * - MochiKit.Async: http://www.mochikit.com/
+ *
+ * @module jarmon
  */
 
+/**
+ * A namespace for Jarmon
+ *
+ * @class jarmon
+ * @static
+ */
 if(typeof jarmon == 'undefined') {
     var jarmon = {};
 }
 
-/**
- * Download a binary file asynchronously using the jQuery.ajax function
- *
- * @param url: The url of the object to be downloaded
- * @return: A I{MochiKit.Async.Deferred} which will callback with an instance of
- *          I{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 = new MochiKit.Async.Deferred();
 
     $.ajax({
@@ -61,50 +71,16 @@ jarmon.downloadBinary = function(url) {
     return d;
 };
 
-/**
- * Limit the number of parallel async calls
- *
- * @param limit: The maximum number of in progress calls
- **/
-jarmon.Parallimiter = function(limit) {
-    this.limit = limit || 1;
-    this._callQueue = [];
-    this._currentCallCount = 0;
-};
-
-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
-    *
-    * @param callable: A function which returns a Deferred.
-    **/
-    var d = new MochiKit.Async.Deferred();
-    this._callQueue.unshift([d, callable, args]);
-    this._nextCall();
-    return d;
-};
-
-jarmon.Parallimiter.prototype._nextCall = function() {
-    if(this._callQueue.length > 0) {
-        if(this._currentCallCount < this.limit) {
-            this._currentCallCount++;
-            var nextCall = this._callQueue.pop();
-            nextCall[1].apply(null, nextCall[2]).addBoth(
-                function(self, d, res) {
-                    d.callback(res);
-                    self._currentCallCount--;
-                    self._nextCall();
-                }, this, nextCall[0]);
-        }
-    }
-};
-
 
 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 = {
@@ -155,14 +131,10 @@ jarmon.localTimeFormatter = function (v, axis) {
  * convenient way to query the RRDFile based on time range, RRD data source (DS)
  * and RRD consolidation function (CF).
  *
- * @param startTime: A javascript {Date} instance representing the start of query
- *                   time range, or {null} to return earliest available data.
- * @param endTime: A javascript {Date} instance representing the end of query
- *                   time range, or {null} to return latest available data.
- * @param dsId: A {String} name of an RRD DS or an {Int} DS index number or
- *              {null} to return the first available DS.
- * @param cfName: A {String} name of an RRD consolidation function
- * @return: A flot compatible data series object
+ * @class jarmon.RrdQuery
+ * @constructor
+ * @param rrd {Object} A javascriptrrd.RRDFile
+ * @param unit {String} The unit symbol for this data series
  **/
 jarmon.RrdQuery = function(rrd, unit) {
     this.rrd = rrd;
@@ -175,14 +147,14 @@ jarmon.RrdQuery.prototype.getData = function(startTime, endTime, dsId, cfName) {
      * end time. The rows are taken from the first RRA whose data spans the
      * requested time range.
      *
-     * @param startTime: The I{Date} start time
-     * @param endTime: The I{Date} end time
-     * @param dsId: An index I{Number} or key I{String} identifying the RRD
-     *              datasource (DS).
-     * @param cfName: The name I{String} of an RRD consolidation function (CF)
-     *                eg AVERAGE, MIN, MAX
-     * @return: A Flot compatible data series I{Object}
-     *          eg {label:'', data:[], unit: ''}
+     * @method getData
+     * @param startTime {Number} start timestamp
+     * @param endTime {Number} 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
+     * @return {Object} A Flot compatible data series
+     *      eg label: '', data: [], unit: ''
      **/
     var startTimestamp = startTime/1000;
 
@@ -258,8 +230,12 @@ jarmon.RrdQuery.prototype.getData = function(startTime, endTime, dsId, cfName) {
  * A wrapper around RrdQuery which provides asynchronous access to the data in a
  * remote RRD file.
  *
- * @param url: The url I{String} of a remote RRD file
- * @param unit: The unit suffix I{String} of this data eg 'bit/sec'
+ * @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.
  **/
 jarmon.RrdQueryRemote = function(url, unit, downloader) {
     this.url = url;
@@ -273,10 +249,11 @@ jarmon.RrdQueryRemote.prototype.getData = function(startTime, endTime, dsId) {
     /**
      * Return a Flot compatible data series asynchronously.
      *
-     * @param startTime: The start time I{Date}
-     * @param endTime: The end time I{Date}
-     * @returns: A I{MochiKit.Async.Deferred} which calls back with a flot data
-     *           series object I{Object}
+     * @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)
+     * @return {Object} A Deferred which calls back with a flot data series.
      **/
     var endTimestamp = endTime/1000;
 
@@ -320,11 +297,13 @@ jarmon.RrdQueryRemote.prototype.getData = function(startTime, endTime, dsId) {
 };
 
 /**
- * Wraps a I{RrdQueryRemote} to provide access to a different RRD DSs within a
+ * Wraps RrdQueryRemote to provide access to a different RRD DSs within a
  * single RrdDataSource.
  *
- * @param rrdQuery: An I{RrdQueryRemote}
- * @param dsId: An index or keyname of an RRD DS
+ * @class jarmon.RrdQueryDsProxy
+ * @constructor
+ * @param rrdQuery {Object} An RrdQueryRemote instance
+ * @param dsId {Variant} identifier of the RRD datasource (string or number)
  **/
 jarmon.RrdQueryDsProxy = function(rrdQuery, dsId) {
     this.rrdQuery = rrdQuery;
@@ -335,6 +314,11 @@ jarmon.RrdQueryDsProxy = function(rrdQuery, dsId) {
 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);
 };
@@ -343,10 +327,12 @@ jarmon.RrdQueryDsProxy.prototype.getData = function(startTime, endTime) {
 /**
  * A class for creating a Flot chart from a series of RRD Queries
  *
- * @param template: A I{jQuery} containing a single element into which the chart
- *                  will be drawn
- * @param options: An I{Object} containing Flot options which describe how the
- *                 chart should be drawn.
+ * @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.
  **/
 jarmon.Chart = function(template, options) {
     this.template = template;
@@ -366,13 +352,13 @@ jarmon.Chart = function(template, options) {
 
 
     this.options['yaxis']['ticks'] = function(axis) {
-        /**
+        /*
          * Choose a suitable SI multiplier based on the min and max values from
          * the axis and then generate appropriate yaxis tick labels.
          *
          * @param axis: An I{Object} with min and max properties
          * @return: An array of ~5 tick labels
-         **/
+         */
         var siPrefixes = {
             0: '',
             1: 'K',
@@ -431,11 +417,12 @@ jarmon.Chart.prototype.addData = function(label, db, enabled) {
      * Add details of a remote RRD data source whose data will be added to this
      * chart.
      *
-     * @param label: A I{String} label for this data which will be shown in the
+     * @method addData
+     * @param label {String} The label for this data which will be shown in the
      *               chart legend
-     * @param db: The url of the remote RRD database
-     * @param enabled: true if you want this data plotted on the chart, false
-     *                 if not.
+     * @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;
@@ -447,8 +434,9 @@ jarmon.Chart.prototype.switchDataEnabled = function(label) {
     /**
      * Enable / Disable a single data source
      *
-     * @param label: The label I{String} of the data source to be enabled /
-     *               disabled
+     * @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) {
@@ -461,8 +449,9 @@ jarmon.Chart.prototype.setTimeRange = function(startTime, endTime) {
     /**
      * Alter the time range of this chart and redraw
      *
-     * @param startTime: The start time I{Date}
-     * @param endTime: The end time I{Date}
+     * @method setTimeRange
+     * @param startTime {Number} The start timestamp
+     * @param endTime {Number} The end timestamp
      **/
     this.startTime = startTime;
     this.endTime = endTime;
@@ -475,8 +464,9 @@ jarmon.Chart.prototype.draw = function() {
      * A 'chart_loading' event is triggered before the data is requested
      * A 'chart_loaded' event is triggered when the chart has been drawn
      *
-     * @return: A I{MochiKit.Async.Deferred} which calls back with the chart
-     *          data when the chart has been rendered.
+     * @method draw
+     * @return {Object} A Deferred which calls back with the chart data when
+     *      the chart has been rendered.
      **/
     this.template.addClass('loading');
 
@@ -584,13 +574,15 @@ jarmon.Chart.prototype.draw = function() {
 
 jarmon.Chart.fromRecipe = function(recipes, templateFactory, downloader) {
     /**
-     * A factory function to generate a list of I{Chart} from a list of recipes
-     * and a list of available rrd files in collectd path format.
+     * A static factory method to generate a list of I{Chart} from a list of
+     * recipes and a list of available rrd files in collectd path format.
      *
-     * @param rrdUrlList: A list of rrd download paths
-     * @param recipes: A list of recipe objects
-     * @param templateFactory: A callable which generates an html template for a
-     *      chart.
+     * @method fromRecipe
+     * @param recipes {Array} A list of recipe objects.
+     * @param templateFactory {Function} A callable which generates an html
+     *      template for a chart.
+     * @param downloader {Function} A download function which returns a Deferred
+     * @return {Array} A list of Chart objects
      **/
 
     var charts = [];
@@ -687,8 +679,10 @@ 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.
  *
- * @param ui: A one element I{jQuery} containing an input form and placeholders
- *            for the timeline and for the series of charts.
+ * @class jarmon.ChartCoordinator
+ * @constructor
+ * @param ui {Object} A one element jQuery containing an input form and
+ *      placeholders for the timeline and for the series of charts.
  **/
 jarmon.ChartCoordinator = function(ui) {
     var self = this;
@@ -799,6 +793,8 @@ 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 selection = this.ui.find('[name="from_standard"]').val();
@@ -891,8 +887,9 @@ jarmon.ChartCoordinator.prototype.setTimeRange = function(from, to) {
     /**
      * Set the start and end time fields in the form and trigger an update
      *
-     * @param startTime: The start time I{Date}
-     * @param endTime: The end time I{Date}
+     * @method setTimeRange
+     * @param startTime {Number} The start timestamp
+     * @param endTime {Number} The end timestamp
      **/
     if(from != null) {
         this.ui.find('[name="from"]').val(from);
@@ -905,7 +902,53 @@ jarmon.ChartCoordinator.prototype.setTimeRange = function(from, to) {
 jarmon.ChartCoordinator.prototype.init = function() {
     /**
      * Reset all charts and the input form to the default time range - last hour
+     *
+     * @method init
      **/
     this.update();
 };
 
+/**
+ * Limit the number of parallel async calls
+ *
+ * @class jarmon.Parallimiter
+ * @constructor
+ * @param limit {Number} The maximum number of in progress calls
+ **/
+jarmon.Parallimiter = function(limit) {
+    this.limit = limit || 1;
+    this._callQueue = [];
+    this._currentCallCount = 0;
+};
+
+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 MochiKit.Async.Deferred();
+    this._callQueue.unshift([d, callable, args]);
+    this._nextCall();
+    return d;
+};
+
+jarmon.Parallimiter.prototype._nextCall = function() {
+    if(this._callQueue.length > 0) {
+        if(this._currentCallCount < this.limit) {
+            this._currentCallCount++;
+            var nextCall = this._callQueue.pop();
+            nextCall[1].apply(null, nextCall[2]).addBoth(
+                function(self, d, res) {
+                    d.callback(res);
+                    self._currentCallCount--;
+                    self._nextCall();
+                }, this, nextCall[0]);
+        }
+    }
+};