diff options
Diffstat (limited to 'jarmon/jarmon.js')
| -rw-r--r-- | jarmon/jarmon.js | 166 |
1 files changed, 120 insertions, 46 deletions
diff --git a/jarmon/jarmon.js b/jarmon/jarmon.js index 9ce3b89..7407bcb 100644 --- a/jarmon/jarmon.js +++ b/jarmon/jarmon.js @@ -25,12 +25,21 @@ if(typeof(jarmon) === 'undefined') { } /** - * Download a binary file asynchronously using the jQuery.ajax function - * - * @method + * @callback jarmon.RrdQueryRemote.Downloader * @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 + * @return {module:jQuery.Deferred} A Deferred which will callback with an + * instance of {@link module:javascriptRRD/binaryXHR.BinaryFile} + */ + +/** + * Download a binary file asynchronously using the {@link jQuery.ajax} + * function. + * + * @member + * @type jarmon.RrdQueryRemote.Downloader + * + * @requires jQuery + * @requires javascriptRRD/binaryXHR */ jarmon.downloadBinary = function(url) { var d = jQuery.Deferred(); @@ -69,6 +78,8 @@ jarmon.downloadBinary = function(url) { * adjustment. * * @method + * @requires Flot + * * @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 @@ -122,12 +133,12 @@ jarmon.localTimeFormatter = function (v, axis) { /** - * 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). + * A wrapper around an instance of {@link module: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). * * @constructor - * @param rrd {javascriptRRD~rrdFile~RRDFile} + * @param rrd {module:javascriptRRD/rrdFile.RRDFile} * @param unit {string} The unit symbol for this data series **/ jarmon.RrdQuery = function(rrd, unit) { @@ -147,9 +158,9 @@ jarmon.RrdQuery = function(rrd, unit) { * @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: '' + * performs a transformation of the values returned from the RRD file. + * @return {module:Flot.data} A Flot compatible data series + * eg `{label: '', data: [], unit: ''}` **/ jarmon.RrdQuery.prototype.getData = function(startTimeJs, endTimeJs, dsId, cfName, transformer) { @@ -268,15 +279,15 @@ jarmon.RrdQuery.prototype.getDSNames = function() { /** - * A wrapper around RrdQuery which provides asynchronous access to the data in a - * remote RRD file. + * A wrapper around {@link jarmon.RrdQuery} which provides asynchronous access + * to the data in a remote RRD file. * * @constructor + * @requires javascriptRRD/rrdFile + * * @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. + * @param [downloader=jarmon.downloadBinary] {jarmon.RrdQueryRemote.Downloader} **/ jarmon.RrdQueryRemote = function(url, unit, downloader) { this.url = url; @@ -292,15 +303,15 @@ jarmon.RrdQueryRemote = function(url, unit, downloader) { }; /** - * Asynchronously call a method on the underlying jarmon.RrdQuery. Think of it + * Asynchronously call a method on the underlying {@link 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. + * @return {module:jQuery.Deferred} A Deferred that calls .methodName(args...) on the + * underlying {@link jarmon.RrdQuery}. */ jarmon.RrdQueryRemote.prototype._callRemote = function(methodName, args) { // Download the rrd if there has never been a download and don't start @@ -351,7 +362,7 @@ jarmon.RrdQueryRemote.prototype._callRemote = function(methodName, args) { * (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 + * @return {module:jQuery.Deferred} A Deferred which calls back with a Flot data * series. **/ jarmon.RrdQueryRemote.prototype.getData = function(startTime, endTime, @@ -367,7 +378,8 @@ jarmon.RrdQueryRemote.prototype.getData = function(startTime, endTime, * Return a list of RRD Data Source names * * @method - * @return {jquery~Deferred} A Deferred which calls back with an array of DS names. + * @return {module:jquery.Deferred} A Deferred which calls back with an array of + * DS names. **/ jarmon.RrdQueryRemote.prototype.getDSNames = function() { return this._callRemote('getDSNames'); @@ -390,12 +402,12 @@ jarmon.RrdQueryDsProxy = function(rrdQuery, dsId, transformer) { }; /** - * Call I{RrdQueryRemote.getData} with a particular dsId + * Call I{@link RrdQueryRemote.getData} with a particular dsId * * @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 + * @return {module:jQuery.Deferred} A Deferred which calls back with a Flot data * series. **/ jarmon.RrdQueryDsProxy.prototype.getData = function(startTime, endTime) { @@ -407,10 +419,16 @@ jarmon.RrdQueryDsProxy.prototype.getData = function(startTime, endTime) { * A class for creating a Flot chart from a series of RRD Queries * * @constructor - * @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. + * @requires jQuery + * @requires Flot + * + * @param template {module:jQuery.jQuery} A jQuery containing a single element + * into which the chart will be drawn + * @param recipe {Object} + * @param recipe.title {string} + * @param recipe.data {Array} + * @param recipe.options {module:Flot.options} Flot options which control how + * the chart should be drawn. **/ jarmon.Chart = function(template, recipe, downloader) { this.template = template; @@ -572,11 +590,12 @@ jarmon.Chart.prototype.setTimeRange = function(startTime, endTime) { /** * 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 + * + * - A 'chart_loading' event is triggered before the data is requested + * - A 'chart_loaded' event is triggered when the chart has been drawn * * @method - * @return {jQuery~Deferred} A Deferred which calls back with the chart data + * @return {module:jQuery.Deferred} A Deferred which calls back with the chart data * when the chart has been rendered. **/ jarmon.Chart.prototype.draw = function() { @@ -702,8 +721,12 @@ jarmon.Chart.prototype.draw = function() { /** * Generate a form through which to choose a data source from a remote RRD file * + * @todo Create an example that uses this. + * * @constructor - * @param $tpl {jQuery~jQuery} jQuery object for the DOM node to attach to. + * @requires jQuery + * + * @param $tpl {module:jQuery.jQuery} jQuery object for the DOM node to attach to. **/ jarmon.RrdChooser = function($tpl) { this.$tpl = $tpl; @@ -850,8 +873,12 @@ jarmon.RrdChooser.prototype.drawDsSummary = function() { /** + * UI element to toggle datasources in a graph. + * * @constructor - * @param $tpl {jQuery~jQuery} + * @requires jQuery + * + * @param $tpl {module:jQuery.jQuery} * @param chart {jarmon.Chart} */ jarmon.ChartEditor = function($tpl, chart) { @@ -981,8 +1008,8 @@ jarmon.ChartEditor.prototype.draw = function() { /** * @method * @private - * @param $row {jQuery~jQuery} - * @return {jQuery~jQuery} + * @param $row {module:jQuery.jQuery} + * @return {module:jQuery.jQuery} */ jarmon.ChartEditor.prototype._extractRowValues = function($row) { return $row.find('input[type=text]').map( @@ -1024,13 +1051,32 @@ jarmon.ChartEditor.prototype._addDatasourceRow = function(record) { /** + * + * The `recipe` is an array of `["Tab Name", [placeholder-name-list]]` + * pairs. For example: + * + * recipe = [ + * ["System", ["cpu", "memory", "load"]], + * ["Network", ["interface"]] + * ]; + * * @constructor - * @param $tpl {jQuery~jQuery} - * @param recipe {Array} + * @requires jQuery + * @requires jQueryTools/tabs + * @requires jQueryTools/toolbox/history + * + * @param $tpl {module:jQuery.jQuery} + * @param recipe {Array.<Array.<string, Array.<string>>>} An array of + * `["Tab Name", [placeholder-name-list]]` pairs. */ jarmon.TabbedInterface = function($tpl, recipe) { this.$tpl = $tpl; this.recipe = recipe; + /** + * An array of `["placeholder-name", placeholder]` pairs. + * @member + * @type {Array.<Array.<string, module:jQuery.jQuery>>} + */ this.placeholders = []; this.$tabBar = $('<ul/>', {'class': 'css-tabs'}).appendTo($tpl); @@ -1054,7 +1100,7 @@ jarmon.TabbedInterface = function($tpl, recipe) { /** * @method * @param tabName {string} - * @return {jQuery~jQuery} + * @return {module:jQuery.jQuery} A <div> that is the contents of the tab panel. */ jarmon.TabbedInterface.prototype.newTab = function(tabName) { // Add a tab @@ -1083,12 +1129,19 @@ jarmon.TabbedInterface.prototype.setup = function() { /** * Setup chart date range controls and all charts * + * @todo Figure out how to allow `$chartTemplate` to be an HTML5 <template> + * element. + * * @method - * @param $chartTemplate {jQuery~jQuery} - * @param chartRecipes {Object} - * @param $tabTemplate {jQuery~jQuery} - * @param tabRecipes {Object} - * @param $controlPanelTemplate {jQuery~jQuery} + * @requires jQuery + * + * @param $chartTemplate {module:jQuery.jQuery} See {@link jarmon.Chart} + * @param chartRecipes {Object.<string, recipe>} A map of + * placeholder-names (see {@link jarmon.TabbedInterface}) + * to chart recipes (see {@link jarmon.Chart}) + * @param $tabTemplate {module:jQuery.jQuery} See {@link jarmon.TabbedInterface} + * @param tabRecipes {Array} See {@link jarmon.TabbedInterface} + * @param $controlPanelTemplate {module:jQuery.jQuery} * @return {Array.<Array.<jarmon.Chart>, jarmon.TabbedInterface, jarmon.ChartCoordinator>} **/ jarmon.buildTabbedChartUi = function ($chartTemplate, chartRecipes, @@ -1160,8 +1213,13 @@ jarmon.buildTabbedChartUi = function ($chartTemplate, chartRecipes, /** * Options common to all the chart on this page * + * This is not used by Jarmon internally; it is here for convenience to use as + * part of chart recipes passed to {@linkcode jarmon.Chart new jarmon.Chart} (or + * {@linkcode jarmon.buildTabbedChartUi}). + * * @static * @default + * @type module:Flot.options */ jarmon.Chart.BASE_OPTIONS = { grid: { @@ -1198,8 +1256,13 @@ jarmon.Chart.BASE_OPTIONS = { /** * Extra options to generate a stacked chart * + * This is not used by Jarmon internally; it is here for convenience to use as + * part of chart recipes passed to {@linkcode jarmon.Chart new jarmon.Chart} (or + * {@linkcode jarmon.buildTabbedChartUi}). + * * @static * @default + * @type module:Flot.options */ jarmon.Chart.STACKED_OPTIONS = { series: { @@ -1214,7 +1277,12 @@ jarmon.Chart.STACKED_OPTIONS = { /** * A selection of useful time ranges * + * This is an array of `["human description", function]` pairs. + * + * @todo This should probably be a member of jarmon.ChartCoordinator. + * * @member + * @default */ jarmon.timeRangeShortcuts = [ ['last hour', function(now) { return [now-60*60*1000*1, now]; }], @@ -1233,7 +1301,11 @@ jarmon.timeRangeShortcuts = [ * time range and co-ordinates the refreshing of a series of charts. * * @constructor - * @param ui {jQuery~jQuery} A one element jQuery containing an input form and + * @requires jQuery + * @requires jQueryTools/dateinput + * @requires Flot + * + * @param ui {module: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) { @@ -1453,7 +1525,7 @@ jarmon.ChartCoordinator = function(ui, charts) { * range timeline and set the time range of all the charts and redraw. * * @method - * @return {jQuery~Deferred} + * @return {module:jQuery.Deferred} **/ jarmon.ChartCoordinator.prototype.update = function() { var self = this; @@ -1575,6 +1647,8 @@ jarmon.ChartCoordinator.prototype.init = function() { * Limit the number of parallel async calls * * @constructor + * @requires jQuery + * * @param limit {number} The maximum number of in progress calls **/ jarmon.Parallimiter = function(limit) { @@ -1590,7 +1664,7 @@ jarmon.Parallimiter = function(limit) { * @method * @param callable {function} A function which returns a Deferred. * @param args {Array} A list of arguments to pass to the callable - * @return {jQuery~jQuery} A Deferred which fires with the result of the callable + * @return {module:jQuery.jQuery} A Deferred which fires with the result of the callable * when it is called. **/ jarmon.Parallimiter.prototype.addCallable = function(callable, args) { |