From d67a42794b8456bf636c7dc72aa572475b288a58 Mon Sep 17 00:00:00 2001 From: Dan Vanderkam Date: Fri, 23 Nov 2012 23:03:05 -0500 Subject: [PATCH] More correctly-compiling files, plus some more info in closure-todo.txt --- closure-todo.txt | 17 +++++++++++- dygraph-externs.js | 59 +++++++++++++++++++++++++++++++++-------- dygraph-gviz.js | 12 ++++++--- dygraph-interaction-model.js | 62 ++++++++++++++++++++++++++------------------ dygraph-options.js | 3 +-- dygraph-tickers.js | 4 +-- 6 files changed, 113 insertions(+), 44 deletions(-) diff --git a/closure-todo.txt b/closure-todo.txt index 3689460..081b9ed 100644 --- a/closure-todo.txt +++ b/closure-todo.txt @@ -1,11 +1,21 @@ +Many of the functions and methods in the dygraphs source have some form of +Closure annotations on them ("@param", "@return", "@private", etc.). + +These provide some documentation value, but they were largely written by +developers who had never used the Closure Compiler and so the syntax is +often not quite correct. + +This file tracks which files have been fully "closurized", i.e. compile +under the Closure Compiler without any errors or warnings. + Core: - dygraph-canvas.js -- dygraph-gviz.js - dygraph-interaction-model.js - dygraph-layout.js - dygraph-options.js - dygraph-range-selector.js - dygraph.js +x dygraph-gviz.js x dygraph-tickers.js x dygraph-options-reference.js x dygraph-utils.js @@ -20,3 +30,8 @@ Plugins: - plugins/install.js - plugins/legend.js +Here's a command that can be used to build dygraphs using the closure +compiler: +java -jar ../../closure-compiler-read-only/build/compiler.jar --js=dygraph-utils.js --js=dashed-canvas.js --js=dygraph-options-reference.js --js=dygraph-tickers.js --js=dygraph-gviz.js --js_output_file=/tmp/out.js --compilation_level ADVANCED_OPTIMIZATIONS --warning_level VERBOSE --externs dygraph-externs.js + +As each file is closurized, it can be added as a "--js" parameter. diff --git a/dygraph-externs.js b/dygraph-externs.js index dc05172..6e487fd 100644 --- a/dygraph-externs.js +++ b/dygraph-externs.js @@ -23,25 +23,62 @@ G_vmlCanvasManager.initElement = function(canvas) {}; Element.prototype.detachEvent = function(type, fn) {}; +/** + * @typedef {function( + * (number|Date), + * number, + * function(string):*, + * (Dygraph|undefined) + * ):string} + */ +var AxisLabelFormatter; + + +/** + * @typedef {function(number,function(string),Dygraph):string} + */ +var ValueFormatter; + + +/** + * @typedef {Array.>>} + */ +var DygraphDataArray; + +/** + * @constructor + */ +function GVizDataTable() {} + // TODO(danvk): move the Dygraph definitions out of here once I closure-ify dygraphs.js +/** + * @param {!HTMLDivElement|string} div + * @param {DygraphDataArray| + * GVizDataTable| + * string| + * function():(DygraphDataArray|GVizDataTable|string)} file + * @param {Object} attrs + * @constructor + */ +function Dygraph(div, file, attrs) {} /** * @constructor */ -function Dygraph() {} +function DygraphLayout() {} + +/** + * @type {Array} + */ +DygraphLayout.prototype.datasets; + +/** + * @type {DygraphLayout} + */ +Dygraph.prototype.layout_; /** @type {Array.<{elem:Element,type:string,fn:function(!Event):(boolean|undefined|null)}>} */ Dygraph.prototype.registeredEvents_; /** @type {Object} */ Dygraph.DEFAULT_ATTRS; - -/** - * @typedef {function( - * (number|Date), - * number, - * function(string):*, - * (Dygraph|undefined) - * ):string} - */ -Dygraph.AxisLabelFormatter; diff --git a/dygraph-gviz.js b/dygraph-gviz.js index 114263a..49feac5 100644 --- a/dygraph-gviz.js +++ b/dygraph-gviz.js @@ -23,12 +23,18 @@ /** * A wrapper around Dygraph that implements the gviz API. - * @param {Object} container The DOM object the visualization should live in. + * @param {!HTMLDivElement} container The DOM object the visualization should + * live in. + * @constructor */ Dygraph.GVizChart = function(container) { this.container = container; }; +/** + * @param {GVizDataTable} data + * @param {Object.<*>} options + */ Dygraph.GVizChart.prototype.draw = function(data, options) { // Clear out any existing dygraph. // TODO(danvk): would it make more sense to simply redraw using the current @@ -44,7 +50,7 @@ Dygraph.GVizChart.prototype.draw = function(data, options) { /** * Google charts compatible setSelection * Only row selection is supported, all points in the row will be highlighted - * @param {Array} array of the selected cells + * @param {Array.<{row:number}>} selection_array array of the selected cells * @public */ Dygraph.GVizChart.prototype.setSelection = function(selection_array) { @@ -57,7 +63,7 @@ Dygraph.GVizChart.prototype.setSelection = function(selection_array) { /** * Google charts compatible getSelection implementation - * @return {Array} array of the selected cells + * @return {Array.<{row:number,column:number}>} array of the selected cells * @public */ Dygraph.GVizChart.prototype.getSelection = function() { diff --git a/dygraph-interaction-model.js b/dygraph-interaction-model.js index 4df6799..d335f15 100644 --- a/dygraph-interaction-model.js +++ b/dygraph-interaction-model.js @@ -28,10 +28,11 @@ Dygraph.Interaction = {}; * Custom interaction model builders can use it to provide the default * panning behavior. * - * @param { Event } event the event object which led to the startPan call. - * @param { Dygraph} g The dygraph on which to act. - * @param { Object} context The dragging context object (with - * dragStartX/dragStartY/etc. properties). This function modifies the context. + * @param {Event} event the event object which led to the startPan call. + * @param {Dygraph} g The dygraph on which to act. + * @param {Object} context The dragging context object (with + * dragStartX/dragStartY/etc. properties). This function modifies the + * context. */ Dygraph.Interaction.startPan = function(event, g, context) { var i, axis; @@ -106,10 +107,11 @@ Dygraph.Interaction.startPan = function(event, g, context) { * Custom interaction model builders can use it to provide the default * panning behavior. * - * @param { Event } event the event object which led to the movePan call. - * @param { Dygraph} g The dygraph on which to act. - * @param { Object} context The dragging context object (with - * dragStartX/dragStartY/etc. properties). This function modifies the context. + * @param {Event} event the event object which led to the movePan call. + * @param {Dygraph} g The dygraph on which to act. + * @param {Object} context The dragging context object (with + * dragStartX/dragStartY/etc. properties). This function modifies the + * context. */ Dygraph.Interaction.movePan = function(event, g, context) { context.dragEndX = g.dragGetX_(event, context); @@ -176,10 +178,11 @@ Dygraph.Interaction.movePan = function(event, g, context) { * Custom interaction model builders can use it to provide the default * panning behavior. * - * @param { Event } event the event object which led to the endPan call. - * @param { Dygraph} g The dygraph on which to act. - * @param { Object} context The dragging context object (with - * dragStartX/dragStartY/etc. properties). This function modifies the context. + * @param {Event} event the event object which led to the endPan call. + * @param {Dygraph} g The dygraph on which to act. + * @param {Object} context The dragging context object (with + * dragStartX/dragStartY/etc. properties). This function modifies the + * context. */ Dygraph.Interaction.endPan = function(event, g, context) { context.dragEndX = g.dragGetX_(event, context); @@ -213,10 +216,11 @@ Dygraph.Interaction.endPan = function(event, g, context) { * Custom interaction model builders can use it to provide the default * zooming behavior. * - * @param { Event } event the event object which led to the startZoom call. - * @param { Dygraph} g The dygraph on which to act. - * @param { Object} context The dragging context object (with - * dragStartX/dragStartY/etc. properties). This function modifies the context. + * @param {Event} event the event object which led to the startZoom call. + * @param {Dygraph} g The dygraph on which to act. + * @param {Object} context The dragging context object (with + * dragStartX/dragStartY/etc. properties). This function modifies the + * context. */ Dygraph.Interaction.startZoom = function(event, g, context) { context.isZooming = true; @@ -231,10 +235,11 @@ Dygraph.Interaction.startZoom = function(event, g, context) { * Custom interaction model builders can use it to provide the default * zooming behavior. * - * @param { Event } event the event object which led to the moveZoom call. - * @param { Dygraph} g The dygraph on which to act. - * @param { Object} context The dragging context object (with - * dragStartX/dragStartY/etc. properties). This function modifies the context. + * @param {Event} event the event object which led to the moveZoom call. + * @param {Dygraph} g The dygraph on which to act. + * @param {Object} context The dragging context object (with + * dragStartX/dragStartY/etc. properties). This function modifies the + * context. */ Dygraph.Interaction.moveZoom = function(event, g, context) { context.zoomMoved = true; @@ -262,13 +267,19 @@ Dygraph.Interaction.moveZoom = function(event, g, context) { context.prevDragDirection = context.dragDirection; }; +/** + * @param {Dygraph} g + * @param {Event} event + * @param {Object} context + */ Dygraph.Interaction.treatMouseOpAsClick = function(g, event, context) { var clickCallback = g.attr_('clickCallback'); var pointClickCallback = g.attr_('pointClickCallback'); var selectedPoint = null; - // Find out if the click occurs on a point. This only matters if there's a pointClickCallback. + // Find out if the click occurs on a point. This only matters if there's a + // pointClickCallback. if (pointClickCallback) { var closestIdx = -1; var closestDistance = Number.MAX_VALUE; @@ -311,10 +322,11 @@ Dygraph.Interaction.treatMouseOpAsClick = function(g, event, context) { * Custom interaction model builders can use it to provide the default * zooming behavior. * - * @param { Event } event the event object which led to the endZoom call. - * @param { Dygraph} g The dygraph on which to end the zoom. - * @param { Object} context The dragging context object (with - * dragStartX/dragStartY/etc. properties). This function modifies the context. + * @param {Event} event the event object which led to the endZoom call. + * @param {Dygraph} g The dygraph on which to end the zoom. + * @param {Object} context The dragging context object (with + * dragStartX/dragStartY/etc. properties). This function modifies the + * context. */ Dygraph.Interaction.endZoom = function(event, g, context) { context.isZooming = false; diff --git a/dygraph-options.js b/dygraph-options.js index cc8c770..4864de9 100644 --- a/dygraph-options.js +++ b/dygraph-options.js @@ -17,11 +17,10 @@ */ /** - * @constructor - * * This parses attributes into an object that can be easily queried. * * @param {Dyraph} dygraph The chart to which these options belong. + * @constructor */ var DygraphOptions = function(dygraph) { this.dygraph_ = dygraph; diff --git a/dygraph-tickers.js b/dygraph-tickers.js index 1395d23..fa8d342 100644 --- a/dygraph-tickers.js +++ b/dygraph-tickers.js @@ -207,7 +207,7 @@ Dygraph.numericTicks = function(a, b, pixels, opts, dygraph, vals) { m_labels = [ "m", "u", "n", "p", "f", "a", "z", "y" ]; } - var formatter = /**@type{Dygraph.AxisLabelFormatter}*/(opts('axisLabelFormatter')); + var formatter = /**@type{AxisLabelFormatter}*/(opts('axisLabelFormatter')); // Add labels to the ticks. var digitsAfterDecimal = /** @type{number} */(opts('digitsAfterDecimal')); @@ -379,7 +379,7 @@ Dygraph.numDateTicks = function(start_time, end_time, granularity) { * @return {!Dygraph.TickList} */ Dygraph.getDateAxis = function(start_time, end_time, granularity, opts, dg) { - var formatter = /** @type{Dygraph.AxisLabelFormatter} */( + var formatter = /** @type{AxisLabelFormatter} */( opts("axisLabelFormatter")); var ticks = []; var t; -- 2.7.4