From 161b49c8de1d9139392bd145db3d03ca380b3f06 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Mon, 12 Dec 2016 16:18:08 -0500 Subject: Documentation improvements --- jarmon/jarmon.js | 166 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 120 insertions(+), 46 deletions(-) (limited to 'jarmon/jarmon.js') 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.>>} 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.>} + */ this.placeholders = []; this.$tabBar = $('
    ', {'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
    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