WIP - Generate TSD Proof of Concept

lib/DOMutil.js

@@ -1,8 +1,18 @@
 // DOM utility methods
 
+/**
+ * @typedef {Object.<string,Element[]>} JSONContainerEntry
+ * @property {Element[]} used
+ * @property {Element[]} redundant
+ */
+
+/**
+ * @typedef {Object.<string, JSONContainerEntry>} JSONContainer
+ */
+
 /**
  * this prepares the JSON container for allocating SVG elements
- * @param {Object} JSONcontainer
+ * @param {JSONContainer} JSONcontainer
  * @private
  */
 exports.prepareElements = function(JSONcontainer) {
@@ -19,7 +29,7 @@ exports.prepareElements = function(JSONcontainer) {
  * this cleans up all the unused SVG elements. By asking for the parentNode, we only need to supply the JSON container from
  * which to remove the redundant elements.
  *
- * @param {Object} JSONcontainer
+ * @param {JSONContainer} JSONcontainer
  * @private
  */
 exports.cleanupElements = function(JSONcontainer) {
@@ -38,7 +48,7 @@ exports.cleanupElements = function(JSONcontainer) {
 
 /**
  * Ensures that all elements are removed first up so they can be recreated cleanly
- * @param {Object} JSONcontainer
+ * @param {JSONContainer} JSONcontainer
  */
 exports.resetElements = function(JSONcontainer) {
   exports.prepareElements(JSONcontainer);
@@ -51,8 +61,8 @@ exports.resetElements = function(JSONcontainer) {
  * the JSON container and the SVG container have to be supplied so other svg containers (like the legend) can use this.
  *
  * @param {string} elementType
- * @param {Object} JSONcontainer
- * @param {Object} svgContainer
+ * @param {JSONContainer} JSONcontainer
+ * @param {HTMLElement} svgContainer
  * @returns {Element}
  * @private
  */
@@ -87,7 +97,7 @@ exports.getSVGElement = function (elementType, JSONcontainer, svgContainer) {
  * the JSON container and the SVG container have to be supplied so other svg containers (like the legend) can use this.
  *
  * @param {string} elementType
- * @param {Object} JSONcontainer
+ * @param {JSONContainer} JSONcontainer
  * @param {Element} DOMContainer
  * @param {Element} insertBefore
  * @returns {*}
@@ -137,11 +147,11 @@ exports.getDOMElement = function (elementType, JSONcontainer, DOMContainer, inse
  *
  * @param {number} x
  * @param {number} y
- * @param {Object} groupTemplate: A template containing the necessary information to draw the datapoint e.g., {style: 'circle', size: 5, className: 'className' }
- * @param {Object} JSONcontainer
- * @param {Object} svgContainer
- * @param {Object} labelObj
- * @returns {vis.PointItem}
+ * @param {GroupTemplate} groupTemplate
+ * @param {JSONContainer} JSONcontainer
+ * @param {HTMLElement} svgContainer
+ * @param {Element} labelObj
+ * @returns {PointItem}
  */
 exports.drawPoint = function(x, y, groupTemplate, JSONcontainer, svgContainer, labelObj) {
   var point;
@@ -197,8 +207,8 @@ exports.drawPoint = function(x, y, groupTemplate, JSONcontainer, svgContainer, l
  * @param {number} width
  * @param {number} height
  * @param {string} className
- * @param {Object} JSONcontainer
- * @param {Object} svgContainer
+ * @param {JSONContainer} JSONcontainer
+ * @param {HTMLElement} svgContainer
  * @param {string} style
  */
 exports.drawBar = function (x, y, width, height, className, JSONcontainer, svgContainer, style) {
@@ -207,7 +217,7 @@ exports.drawBar = function (x, y, width, height, className, JSONcontainer, svgCo
       height *= -1;
       y -= height;
     }
-    var rect = exports.getSVGElement('rect',JSONcontainer, svgContainer);
+    var rect = exports.getSVGElement('rect', JSONcontainer, svgContainer);
     rect.setAttributeNS(null, "x", x - 0.5 * width);
     rect.setAttributeNS(null, "y", y);
     rect.setAttributeNS(null, "width", width);

lib/DataSet.js

@@ -1,11 +1,21 @@
 var util = require('./util');
 var Queue = require('./Queue');
 
+/**
+ * @typedef  {Object.<string,*>}        DataSet~Options
+ * @property {string}                   fieldId - Field name of the id in the items, 'id' by default.
+ * @property {Object.<string,string>}   type - A map with field names as key, and the field type as value.
+ * @property {Queue|Queue~Options}       queue - Queue changes to the DataSet, flush them all at once.
+ */
+
 /**
  * DataSet
- * // TODO: add a DataSet constructor DataSet(data, options)
+ * A data set can:
+ * - add/remove/update data
+ * - gives triggers upon changes in the data
+ * - can  import/export data in various data formats
  *
- * Usage:
+ * @example
  *     var dataSet = new DataSet({
  *         fieldId: '_id',
  *         type: {
@@ -25,24 +35,11 @@ var Queue = require('./Queue');
  *     var data = dataSet.get(ids, options, data);
  *     dataSet.clear();
  *
- * A data set can:
- * - add/remove/update data
- * - gives triggers upon changes in the data
- * - can  import/export data in various data formats
+ * @param {Array.<Item>}    [data]    Optional array with initial data
+ * @param {DataSet~Options}  [options]
  *
- * @param {Array} [data]    Optional array with initial data
- * @param {Object} [options]   Available options:
- *                             {string} fieldId Field name of the id in the
- *                                              items, 'id' by default.
- *                             {Object.<string, string} type
- *                                              A map with field names as key,
- *                                              and the field type as value.
- *                             {Object} queue   Queue changes to the DataSet,
- *                                              flush them all at once.
- *                                              Queue options:
- *                                              - {number} delay  Delay in ms, null by default
- *                                              - {number} max    Maximum number of entries in the queue, Infinity by default
  * @constructor DataSet
+ * @todo add a DataSet constructor DataSet(data, options)
  */
 function DataSet (data, options) {
   // correctly read optional arguments

lib/Queue.js

@@ -1,14 +1,15 @@
+/**
+ * @typedef {Object.<string,number>} Queue~Options
+ * @property {number} [delay=null]   When provided, the queue will be flushed
+ *                                   automatically after an inactivity of this delay
+ *                                   in milliseconds.
+ * @property {number} [max=Infinity] When the queue exceeds the given maximum number
+ *                                   of entries, the queue is flushed automatically.
+ */
+
 /**
  * A queue
- * @param {Object} options
- *            Available options:
- *            - delay: number    When provided, the queue will be flushed
- *                               automatically after an inactivity of this delay
- *                               in milliseconds.
- *                               Default value is null.
- *            - max: number      When the queue exceeds the given maximum number
- *                               of entries, the queue is flushed automatically.
- *                               Default value of max is Infinity.
+ * @param {Queue~Options} options
  * @constructor Queue
  */
 function Queue(options) {

lib/graph3d/DataGroup.js

@@ -32,7 +32,7 @@ function DataGroup() {
  * the given instance.
  * TODO: Pass settings only instead.
  *
- * @param {vis.Graph3d}  graph3d Reference to the calling Graph3D instance.
+ * @param {Graph3d}  graph3d Reference to the calling Graph3D instance.
  * @param {Array | DataSet | DataView} rawData The data containing the items for
  *                                             the Graph.
  * @param {number}   style   Style Number
@@ -143,7 +143,7 @@ DataGroup.prototype.initializeData = function(graph3d, rawData, style) {
  * @private
  *
  * @param {'x'|'y'|'z'} column  The data column to process
- * @param {vis.Graph3d} graph3d Reference to the calling Graph3D instance;
+ * @param {Graph3d} graph3d Reference to the calling Graph3D instance;
  *                              required for access to settings
  * @returns {Object}
  */
@@ -176,7 +176,7 @@ DataGroup.prototype._collectRangeSettings = function(column, graph3d) {
  *
  * @param {DataSet | DataView} data     The data containing the items for the Graph
  * @param {'x'|'y'|'z'}        column   The data column to process
- * @param {vis.Graph3d}        graph3d  Reference to the calling Graph3D instance;
+ * @param {Graph3d}        graph3d  Reference to the calling Graph3D instance;
  *                                      required for access to settings
  * @param {boolean}            withBars True if initializing for bar graph
  */
@@ -292,7 +292,7 @@ DataGroup.prototype.getNumberOfRows = function() {
  * to pass in a range already set with the min/max set from the data. Otherwise,
  * it's quite hard to process the min/max properly.
  *
- * @param {vis.Range} range
+ * @param {Range} range
  * @param {number} [defaultMin=range.min]
  * @param {number} [defaultMax=range.max]
  * @private

lib/graph3d/Graph3d.js

@@ -21,6 +21,8 @@ Graph3d.STYLE = Settings.STYLE;
  *
  * Using 'undefined' directly achieves the same thing, but this is more
  * descriptive by describing the intent.
+ *
+ * @ignore
  */
 var autoByDefault = undefined;
 
@@ -32,6 +34,8 @@ var autoByDefault = undefined;
  *
  * If a field is not in this list, a default value of 'autoByDefault' is assumed,
  * which is just an alias for 'undefined'.
+ *
+ * @ignore
  */
 Graph3d.DEFAULTS = {
   width            : '400px',
@@ -356,7 +360,7 @@ Graph3d.prototype._initializeRanges = function() {
 /**
  * Return all data values as a list of Point3d objects
  *
- * @param {vis.DataSet} data
+ * @param {DataSet} data
  * @returns {Array.<Object>}
  */
 Graph3d.prototype.getDataPoints = function(data) {
@@ -617,7 +621,7 @@ Graph3d.prototype.getCameraPosition = function() {
 /**
  * Load data into the 3D Graph
  *
- * @param {vis.DataSet} data
+ * @param {DataSet} data
  * @private
  */
 Graph3d.prototype._readData = function(data) {
@@ -976,8 +980,8 @@ Graph3d.prototype._redrawInfo = function() {
  * If stroke style specified, set that as well.
  *
  * @param {CanvasRenderingContext2D} ctx
- * @param {vis.Point2d} from
- * @param {vis.Point2d} to
+ * @param {Point2d} from
+ * @param {Point2d} to
  * @param {string} [strokeStyle]
  * @private
  */
@@ -995,7 +999,7 @@ Graph3d.prototype._line = function(ctx, from, to, strokeStyle) {
 /**
  *
  * @param {CanvasRenderingContext2D} ctx
- * @param {vis.Point3d} point3d
+ * @param {Point3d} point3d
  * @param {string} text
  * @param {number} armAngle
  * @param {number} [yMargin=0]
@@ -1029,7 +1033,7 @@ Graph3d.prototype.drawAxisLabelX = function(ctx, point3d, text, armAngle, yMargi
 /**
  *
  * @param {CanvasRenderingContext2D} ctx
- * @param {vis.Point3d} point3d
+ * @param {Point3d} point3d
  * @param {string} text
  * @param {number} armAngle
  * @param {number} [yMargin=0]
@@ -1063,7 +1067,7 @@ Graph3d.prototype.drawAxisLabelY = function(ctx, point3d, text, armAngle, yMargi
 /**
  *
  * @param {CanvasRenderingContext2D} ctx
- * @param {vis.Point3d} point3d
+ * @param {Point3d} point3d
  * @param {string} text
  * @param {number} [offset=0]
  */
@@ -1089,8 +1093,8 @@ Graph3d.prototype.drawAxisLabelZ = function(ctx, point3d, text, offset) {
  * If stroke style specified, set that as well.
  *
  * @param {CanvasRenderingContext2D} ctx
- * @param {vis.Point2d} from
- * @param {vis.Point2d} to
+ * @param {Point2d} from
+ * @param {Point2d} to
  * @param {string} [strokeStyle]
  * @private
  */
@@ -1321,7 +1325,7 @@ Graph3d.prototype._hsv2rgb = function(H, S, V) {
 
 /**
  *
- * @param {vis.Point3d} point
+ * @param {Point3d} point
  * @returns {*}
  * @private
  */
@@ -1432,7 +1436,7 @@ Graph3d.prototype._redrawBar = function(ctx, point, xWidth, yWidth, color, borde
  * Draw a polygon using the passed points and fill it with the passed style and stroke.
  *
  * @param {CanvasRenderingContext2D} ctx
- * @param {Array.<vis.Point3d>} points      an array of points.
+ * @param {Array.<Point3d>} points      an array of points.
  * @param {string} [fillStyle] the fill style to set
  * @param {string} [strokeStyle] the stroke style to set
  */
@@ -2130,8 +2134,8 @@ Graph3d.prototype._onWheel = function(event) {
 /**
  * Test whether a point lies inside given 2D triangle
  *
- * @param   {vis.Point2d}   point
- * @param   {vis.Point2d[]} triangle
+ * @param   {Point2d}   point
+ * @param   {Point2d[]} triangle
  * @returns {boolean}   true if given point lies inside or on the edge of the
  *                      triangle, false otherwise
  * @private

lib/graph3d/Point3d.js

@@ -71,7 +71,7 @@ Point3d.crossProduct = function(a, b) {
 
 
 /**
- * Rtrieve the length of the vector (or the distance from this point to the origin
+ * Rtrieve the length of the vector (or the distance) from this point to the origin
  * @return {number}  length
  */
 Point3d.prototype.length = function() {

lib/graph3d/Settings.js

@@ -42,6 +42,7 @@ var STYLENAME = {
  *
  * Specifically, these are the fields which require no special handling,
  * and can be directly copied over.
+ * @ignore
  */
 var OPTIONKEYS = [
   'width',
@@ -81,6 +82,7 @@ var OPTIONKEYS = [
  *
  * Same as OPTIONKEYS, but internally these fields are stored with 
  * prefix 'default' in the name.
+ * @ignore
  */
 var PREFIXEDOPTIONKEYS = [
   'xBarWidth',

lib/graph3d/options.js

@@ -4,6 +4,7 @@
  *
  * __any__ means that the name of the property does not matter.
  * __type__ is a required field for all objects and contains the allowed types of all objects
+ * @ignore
  */
 let string   = 'string';
 let bool     = 'boolean';
@@ -28,6 +29,7 @@ let colorOptions = {
  *   - x/y/z-prefixes ignored in sorting
  *   - __type__ always at end
  *   - globals at end
+ *   @ignore
  */
 let allOptions = {
   animationAutoStart: { boolean: bool, 'undefined': 'undefined' },

lib/hammerUtil.js

@@ -17,7 +17,7 @@ exports.onTouch = function (hammer, callback) {
  * Register a release event, taking place after a gesture
  * @param {Hammer} hammer       A hammer instance
  * @param {function} callback   Callback, called as callback(event)
- * @returns {*}
+ * @returns {function}
  */
 exports.onRelease = function (hammer, callback) {
   callback.inputHandler = function (event) {
@@ -43,6 +43,7 @@ exports.offTouch = function (hammer, callback) {
  * Unregister a release event, taking place before a gesture
  * @param {Hammer} hammer       A hammer instance
  * @param {function} callback   Callback, called as callback(event)
+ * @ignore
  */
 exports.offRelease = exports.offTouch;
 

lib/network/Images.js

@@ -46,7 +46,7 @@ class Images {
 
   /**
    *
-   * @param {vis.Image} imageToRedrawWith
+   * @param {Image} imageToRedrawWith
    * @private
    */
   _redrawWithImage (imageToRedrawWith) {
@@ -99,7 +99,7 @@ class Images {
    * IE11 fix -- thanks dponch!
    *
    * Local helper function
-   * @param {vis.Image} imageToCache
+   * @param {Image} imageToCache
    * @private
    */
     _fixImageCoordinates(imageToCache) {