From b49aa63ca075baa78ac673133bebcb7494eab225 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Sun, 11 Dec 2016 15:18:45 -0500 Subject: Adjust to have better output with jsdoc. --- jarmon/externdoc.js | 46 ++++++++++ jarmon/jarmon.js | 255 ++++++++++++++++++++++++++++++++++------------------ 2 files changed, 212 insertions(+), 89 deletions(-) create mode 100644 jarmon/externdoc.js 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.} 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) { $('').append( $('').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 $('
  • ').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., 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) { -- cgit v1.1-4-g5e80