From 312cfa1a71c75422b8c03ea0fdbeb37bdaca2ee5 Mon Sep 17 00:00:00 2001 From: Richard Wall Date: Sat, 21 Aug 2010 23:59:11 +0100 Subject: Fix doc strings for compatibility with yuidoc --- jarmon.js | 241 ++++++++++++++++++++++++++++++++++++-------------------------- 1 file 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 +/** + * Copyright (c) 2010 Richard Wall * 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 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]); + } + } +}; -- cgit v1.2.3