Documentation improvements

5 files changed, 201 insertions, 95 deletions

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 <https://github.com/jquerytools/jquerytools.github.com/blob/master/media/css/dateinput/skin1.css>.
+ *
+ * Documentation on skinning: <http://jquerytools.github.io/documentation/dateinput/index.html#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.<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) {