From 161b49c8de1d9139392bd145db3d03ca380b3f06 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Mon, 12 Dec 2016 16:18:08 -0500 Subject: Documentation improvements --- .../assets/css/jquerytools.dateinput.skin1.css | 13 +- docs/examples/assets/css/style.css | 2 +- jarmon/external.doc.js | 69 +++++++++ jarmon/externdoc.js | 46 ------ jarmon/jarmon.js | 166 +++++++++++++++------ 5 files changed, 201 insertions(+), 95 deletions(-) create mode 100644 jarmon/external.doc.js delete mode 100644 jarmon/externdoc.js diff --git a/docs/examples/assets/css/jquerytools.dateinput.skin1.css b/docs/examples/assets/css/jquerytools.dateinput.skin1.css index 69aedb8..9c1ce75 100644 --- a/docs/examples/assets/css/jquerytools.dateinput.skin1.css +++ b/docs/examples/assets/css/jquerytools.dateinput.skin1.css @@ -1,4 +1,9 @@ -/* For the details, see: http://flowplayer.org/tools/dateinput/index.html#skinning */ +/* Skin for jQuery Tools dateinput. + * + * Based on . + * + * Documentation on skinning: + */ /* the input field */ .date { @@ -7,7 +12,9 @@ padding:4px; text-align:center; width:194px; + -moz-box-shadow:0 0 10px #eee inset; + -webkit-box-shadow:0 0 10px #eee inset; } /* calendar root element */ @@ -18,8 +25,10 @@ background-color:#fff; font-size:11px; border:1px solid #ccc; + -moz-border-radius:5px; -webkit-border-radius:5px; + -moz-box-shadow: 0 0 15px #666; -webkit-box-shadow: 0 0 15px #666; } @@ -127,7 +136,7 @@ a.caloff:hover { /* unselecteble day */ a.caldisabled { background-color:#efefef !important; - color:#ccc !important; + color:#ccc !important; cursor:default; } diff --git a/docs/examples/assets/css/style.css b/docs/examples/assets/css/style.css index e82ec30..2968265 100644 --- a/docs/examples/assets/css/style.css +++ b/docs/examples/assets/css/style.css @@ -19,7 +19,7 @@ p, li, dt, dd, td, th, div { .loading .title { background-repeat: no-repeat; background-position: 0 50%; - background-image: url(/assets/icons/loading.gif); + background-image: url(../icons/loading.gif); } .range-preview { diff --git a/jarmon/external.doc.js b/jarmon/external.doc.js new file mode 100644 index 0000000..119d1fb --- /dev/null +++ b/jarmon/external.doc.js @@ -0,0 +1,69 @@ +/** + * jQuery + * @module jQuery + * @see http://api.jquery.com/ + */ +/** + * @typedef module:jQuery.jQuery + * @see http://api.jquery.com/Types/#jQuery + */ +/** + * @typedef module:jQuery.Deferred + * @see http://api.jquery.com/category/deferred-object/ + */ +/** + * @function module:jQuery.ajax + * @see https://api.jquery.com/jQuery.ajax/ + */ + +/** + * {@link http://jquerytools.github.io/ jQuery Tools} / dateinput + * @module jQueryTools/dateinput + * @see http://jquerytools.github.io/documentation/dateinput/index.html + */ + +/** + * {@link http://jquerytools.github.io/ jQuery Tools} / tabs + * @module jQueryTools/tabs + * @see http://jquerytools.github.io/documentation/tabs/index.html + */ + +/** + * {@link http://jquerytools.github.io/ jQuery Tools} / toolbox/history + * @module jQueryTools/toolbox/history + * @see http://jquerytools.github.io/documentation/toolbox/history.html + */ + +/** + * {@link http://javascriptrrd.sourceforge.net/docs/javascriptrrd_v1.1.1/doc/lib/index.html javascriptRRD}/binaryXHR + * @module javascriptRRD/binaryXHR + * @see http://javascriptrrd.sourceforge.net/docs/javascriptrrd_v1.1.1/doc/lib/binaryXHR_js.html + */ +/** + * @typedef module:javascriptRRD/binaryXHR.BinaryFile + * @see http://javascriptrrd.sourceforge.net/docs/javascriptrrd_v1.1.1/doc/lib/binaryXHR_js.html#BinaryFile + */ + +/** + * {@link http://javascriptrrd.sourceforge.net/docs/javascriptrrd_v1.1.1/doc/lib/index.html javascriptRRD}/rrdFile + * @module javascriptRRD/rrdFile + * @see http://javascriptrrd.sourceforge.net/docs/javascriptrrd_v1.1.1/doc/lib/rrdFile_js.html + */ +/** + * @typedef module:javascriptRRD/rrdFile.RRDFile + * @see http://javascriptrrd.sourceforge.net/docs/javascriptrrd_v1.1.1/doc/lib/rrdFile_js.html#RRDFile + */ + +/** + * {@link http://www.flotcharts.org/ Flot} + * @module Flot + * @see https://github.com/flot/flot/blob/master/API.md + */ +/** + * @typedef module:Flot.data + * @see https://github.com/flot/flot/blob/master/API.md#data-format + */ +/** + * @typedef module:Flot.options + * @see https://github.com/flot/flot/blob/master/API.md#plot-options + */ diff --git a/jarmon/externdoc.js b/jarmon/externdoc.js deleted file mode 100644 index 55a1d39..0000000 --- a/jarmon/externdoc.js +++ /dev/null @@ -1,46 +0,0 @@ -/** - * @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 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