From 25cc2a9897ee5511cfb8f7504b22ada47908d438 Mon Sep 17 00:00:00 2001 From: David Manthey Date: Tue, 20 Nov 2018 15:20:06 -0500 Subject: [PATCH 1/2] Update the jsdocs for the vector feature. Tolerate no warnings from eslint. Fix a few minor other jsdoc issues. This is the last PR necessary to resolve #448. --- package.json | 2 +- src/d3/graphFeature.js | 1 - src/d3/tileLayer.js | 9 ++- src/d3/vectorFeature.js | 132 ++++++++++++++++++++++++---------------- src/graphFeature.js | 2 +- src/layer.js | 5 +- src/vectorFeature.js | 73 +++++++++++++++++----- 7 files changed, 151 insertions(+), 73 deletions(-) diff --git a/package.json b/package.json index 5dfa3bc5c4..ed48be0063 100644 --- a/package.json +++ b/package.json @@ -110,7 +110,7 @@ "build-website-examples": "node examples/build-website.js && webpack --config webpack-website-examples.config.js", "build-tutorials": "node tutorials/build.js && webpack --config webpack-tutorials.config.js", "build-website-tutorials": "node tutorials/build-website.js && webpack --config webpack-website-tutorials.config.js", - "lint": "eslint --cache .", + "lint": "eslint --cache . --max-warnings=0", "puglint": "pug-lint src examples", "test": "GEOJS_TEST_CASE=tests/test-unit.js karma start karma-cov.conf.js --single-run --browsers ChromeHeadlessTouch,FirefoxHeadlessTouch,PhantomJS", "test-all": "GEOJS_TEST_CASE=tests/test-unit.js karma start karma-cov.conf.js --single-run --browsers ChromeHeadlessTouch,FirefoxHeadlessTouch,PhantomJS", diff --git a/src/d3/graphFeature.js b/src/d3/graphFeature.js index a6dbfc2de3..52f65b1119 100644 --- a/src/d3/graphFeature.js +++ b/src/d3/graphFeature.js @@ -8,7 +8,6 @@ var graphFeature = require('../graphFeature'); * @class * @alias geo.d3.graphFeature * @extends geo.graphFeature - * @extends geo.d3.object * @param {geo.graphFeature.spec} arg Feature options. * @returns {geo.graphFeature} */ diff --git a/src/d3/tileLayer.js b/src/d3/tileLayer.js index 697470fd30..8d6031b239 100644 --- a/src/d3/tileLayer.js +++ b/src/d3/tileLayer.js @@ -41,7 +41,11 @@ var d3_tileLayer = function () { m_this.draw(); }; - /* Remove the tile feature. */ + /** + * Remove the tile feature. + * + * @param {geo.tile} tile The tile to remove. + */ this._remove = function (tile) { if (tile.quadId !== undefined && m_quadFeature) { for (var i = 0; i < m_tiles.length; i += 1) { @@ -66,7 +70,8 @@ var d3_tileLayer = function () { s_exit.apply(m_this, arguments); }; - /* Initialize the tile layer. This creates a series of sublayers so that + /** + * Initialize the tile layer. This creates a series of sublayers so that * the different layers will stack in the proper order. */ this._init = function () { diff --git a/src/d3/vectorFeature.js b/src/d3/vectorFeature.js index f1898975b5..dd38f69b4c 100644 --- a/src/d3/vectorFeature.js +++ b/src/d3/vectorFeature.js @@ -2,14 +2,67 @@ var inherit = require('../inherit'); var registerFeature = require('../registry').registerFeature; var vectorFeature = require('../vectorFeature'); +/* These markers are available to all instances of the vectorFeature. */ +var markerConfigs = { + arrow: { + attrs: { + class: 'geo-vector-arrow geo-vector-marker', + viewBox: '0 0 10 10', + refX: 1, + refY: 5, + markerHeight: 5, + markerWidth: 5, + orient: 'auto' + }, + path: 'M 0 0 L 10 5 L 0 10 z' + }, + point: { + attrs: { + class: 'geo-vector-point geo-vector-marker', + viewBox: '0 0 12 12', + refX: 6, + refY: 6, + markerHeight: 8, + markerWidth: 8, + orient: 'auto' + }, + path: 'M 6 3 A 3 3 0 1 1 5.99999 3 Z' + }, + bar: { + attrs: { + class: 'geo-vector-bar geo-vector-marker', + viewBox: '0 0 10 10', + refX: 0, + refY: 5, + markerHeight: 6, + markerWidth: 6, + orient: 'auto' + }, + path: 'M 0 0 L 2 0 L 2 10 L 0 10 z' + }, + wedge: { + attrs: { + class: 'geo-vector-wedge geo-vector-marker', + viewBox: '0 0 10 10', + refX: 10, + refY: 5, + markerHeight: 5, + markerWidth: 5, + orient: 'auto' + }, + path: 'M 0 0 L 1 0 L 10 5 L 1 10 L 0 10 L 9 5 L 0 0' + } +}; + /** - * Create a new instance of vectorFeature + * Create a new instance of d3.vectorFeature. * * @class * @alias geo.d3.vectorFeature * @extends geo.vectorFeature * @extends geo.d3.object - * @returns {geo.d3.vectorFeature} + * @param {geo.vectorFeature.spec} arg Feature options. + * @returns {geo.vectorFeature} */ var d3_vectorFeature = function (arg) { 'use strict'; @@ -29,18 +82,19 @@ var d3_vectorFeature = function (arg) { * @private */ var m_this = this, - s_init = this._init, s_exit = this._exit, s_update = this._update, m_buildTime = timestamp(), m_style = {}; /** - * Generate a unique ID for a marker definition - * @private - * @param {object} d Unused datum (for d3 compat) - * @param {number} i The marker index - * @param {string} position The marker's vector position (head or tail) + * Generate a unique ID for a marker definition. + * + * @param {object} d The marker datum (unused). + * @param {number} i The marker index. + * @param {string} position The marker's vector position (`'head'` or + * `'tail'`). + * @returns {string} The constructed ID. */ function markerID(d, i, position) { return m_this._d3id() + '_marker_' + i + '_' + position; @@ -48,35 +102,15 @@ var d3_vectorFeature = function (arg) { /** * Add marker styles for vector arrows. - * @private - * @param {object[]} data The vector data array - * @param {function} stroke The stroke accessor - * @param {function} opacity The opacity accessor - * @param {function} originStyle The marker style for the vector head - * @param {function} endStyle The marker style for the vector tail + * + * @param {object[]} data The vector data array. + * @param {function} stroke The stroke accessor. + * @param {function} opacity The opacity accessor. + * @param {function} originStyle The marker style for the vector head. + * @param {function} endStyle The marker style for the vector tail. */ function updateMarkers(data, stroke, opacity, originStyle, endStyle) { - - var markerConfigs = { - 'arrow': { - attrs: {'class': 'geo-vector-arrow geo-vector-marker', 'viewBox': '0 0 10 10', 'refX': '1', 'refY': '5', 'markerHeight': '5', 'markerWidth': '5', 'orient': 'auto'}, - path: 'M 0 0 L 10 5 L 0 10 z' - }, - 'point': { - attrs: {'class': 'geo-vector-point geo-vector-marker', 'viewBox': '0 0 12 12', 'refX': '6', 'refY': '6', 'markerHeight': '8', 'markerWidth': '8', 'orient': 'auto'}, - path: 'M 6 3 A 3 3 0 1 1 5.99999 3 Z' - }, - 'bar': { - attrs: {'class': 'geo-vector-bar geo-vector-marker', 'viewBox': '0 0 10 10', 'refX': '0', 'refY': '5', 'markerHeight': '6', 'markerWidth': '6', 'orient': 'auto'}, - path: 'M 0 0 L 2 0 L 2 10 L 0 10 z' - }, - 'wedge': { - attrs: {'class': 'geo-vector-wedge geo-vector-marker', 'viewBox': '0 0 10 10', 'refX': '10', 'refY': '5', 'markerHeight': '5', 'markerWidth': '5', 'orient': 'auto'}, - path: 'M 0 0 L 1 0 L 10 5 L 1 10 L 0 10 L 9 5 L 0 0' - } - }; - - //this allows for multiple VectorFeatures in a layer + //this allows for multiple vectorFeature in a layer var markerGroup = m_this.renderer()._definitions() .selectAll('g.marker-group#' + m_this._d3id()) .data(data.length ? [1] : []); @@ -148,17 +182,9 @@ var d3_vectorFeature = function (arg) { } /** - * Initialize - * @protected - */ - this._init = function (arg) { - s_init.call(m_this, arg); - return m_this; - }; - - /** - * Build - * @protected + * Build. + * + * @returns {this}. */ this._build = function () { var data = m_this.data(), @@ -168,7 +194,7 @@ var d3_vectorFeature = function (arg) { size_func = m_this.delta(), cache = [], scale = m_this.style('scale'), - max = Number.NEGATIVE_INFINITY; + max = 0; // call super-method s_update.call(m_this); @@ -191,7 +217,7 @@ var d3_vectorFeature = function (arg) { max = Math.sqrt(max); if (!scale) { - scale = 75 / max; + scale = 75 / (max ? max : 1); } function getScale() { @@ -246,8 +272,9 @@ var d3_vectorFeature = function (arg) { }; /** - * Update - * @protected + * Update. + * + * @returns {this} */ this._update = function () { s_update.call(m_this); @@ -268,8 +295,7 @@ var d3_vectorFeature = function (arg) { }; /** - * Exit - * @protected + * Exit. Remove markers. */ this._exit = function () { s_exit.call(m_this); @@ -281,6 +307,8 @@ var d3_vectorFeature = function (arg) { return this; }; +d3_vectorFeature.markerConfigs = markerConfigs; + inherit(d3_vectorFeature, vectorFeature); // Now register it diff --git a/src/graphFeature.js b/src/graphFeature.js index 70c4741942..05eca4af3a 100644 --- a/src/graphFeature.js +++ b/src/graphFeature.js @@ -5,7 +5,7 @@ var feature = require('./feature'); * Object specification for a graph feature. * * @typedef {geo.feature.spec} geo.graphFeature.spec - * @property {geo.pointFeature.styleSpec} [style] Style object with default + * @property {geo.graphFeature.styleSpec} [style] Style object with default * style options. */ diff --git a/src/layer.js b/src/layer.js index 59bdf4563b..d6505b0e4c 100644 --- a/src/layer.js +++ b/src/layer.js @@ -14,8 +14,9 @@ var rendererForAnnotations = require('./registry').rendererForAnnotations; * @property {geo.map} [map=null] Parent map of the layer. * @property {string|geo.renderer} [renderer] Renderer to associate with the * layer. If not specified, either `annotations` or `features` can be used - * to determine the renderer. If a `geo.renderer` instance, the renderer is - * not recreated; not all renderers can be shared by multiple layers. + * to determine the renderer. If a {@link geo.renderer} instance, the + * renderer is not recreated; not all renderers can be shared by multiple + * layers. * @property {HTMLElement} [canvas] If specified, use this canvas rather than * a canvas associaied with the renderer directly. Renderers may not support * sharing a canvas. diff --git a/src/vectorFeature.js b/src/vectorFeature.js index 4abbf9d180..5a7d1684e7 100644 --- a/src/vectorFeature.js +++ b/src/vectorFeature.js @@ -2,11 +2,47 @@ var inherit = require('./inherit'); var feature = require('./feature'); /** - * Create a new instance of class vectorFeature + * Object specification for a graph feature. + * + * @typedef {geo.feature.spec} geo.vectorFeature.spec + * @property {geo.vectorFeature.styleSpec} [style] Style object with default + * style options. + * @property {function|object} [origin={x: 0, y: 0, z: 0}] Origin accessor. + * @property {function + */ + +/** + * Style specification for a vector feature. + * + * @typedef {geo.feature.styleSpec} geo.vectorFeature.styleSpec + * @extends geo.feature.styleSpec + * @property {geo.geoColor|function} [strokeColor] Color to stroke each vector. + * @property {number|function} [strokeOpacity] Opacity for each vector. + * Opacity is on a [0-1] scale. + * @property {number|function} [strokeWidth] The weight of the vector stroke in + * pixels. + * @property {string|function} [originStyle='none'] The style at the origin of + * the vector. One of the marker styles or `'none'`. Marker styles are + * usually `'arrow'`, `'point'`, `'bar'`, and `'wedge'`. + * @property {string|function} [endStyle='arrow'] The style at the far end of + * the vector. One of the marker styles or `'none'`. Marker styles are + * usually `'arrow'`, `'point'`, `'bar'`, and `'wedge'`. + * @property {geo.geoPosition|function} [origin={x: 0, y: 0, z: 0}] The origin + * of the vector. One end of the vector will be at this point. + * @property {geo.geoPosition|function} [delta] The direction that the vector + * points in. The length of the vector is dependant on this and the `scale`. + * @property {number|function} [scale] The size of the vector relative to the + * delta. If `null`, `undefined`, or `0`, this is `75 / `. + */ + +/** + * Create a new instance of class vectorFeature. * * @class * @alias geo.vectorFeature * @extends geo.feature + * @param {geo.vectorFeature.spec} arg Feature options. * @returns {geo.vectorFeature} */ var vectorFeature = function (arg) { @@ -24,45 +60,53 @@ var vectorFeature = function (arg) { * @private */ var m_this = this, - s_init = this._init, - s_style = this.style; + s_init = this._init; this.featureType = 'vector'; /** * Get or set the accessor for the origin of the vector. This is the point - * that the vector base resides at. Defaults to (0, 0, 0). - * @param {geo.accessor|geo.geoPosition} [accessor] The origin accessor + * that the vector starts. + * + * @param {geo.geoPosition|function} [val] The new origin if specified. If + * not specified, return the current origin. + * @returns {geo.geoPosition|function|this} Either the current origin or + * this feature. */ this.origin = function (val) { if (val === undefined) { - return s_style('origin'); + return m_this.style('origin'); } else { - s_style('origin', val); + m_this.style('origin', val); m_this.dataTime().modified(); - m_this.modified(); } return m_this; }; /** * Get or set the accessor for the displacement (coordinates) of the vector. - * @param {geo.accessor|geo.geoPosition} [accessor] The accessor + * This is the direction of the vector. + * + * @param {geo.geoPosition|function} [val] The new delta if specified. If + * not specified, return the current delta. + * @returns {geo.geoPosition|function|this} Either the current delta or this + * feature. */ this.delta = function (val) { if (val === undefined) { - return s_style('delta'); + return m_this.style('delta'); } else { - s_style('delta', val); + m_this.style('delta', val); m_this.dataTime().modified(); - m_this.modified(); } return m_this; }; /** - * Initialize - * @protected + * Initialize. + * + * @param {geo.vectorFeature.spec} arg The feature specification. + * @returns {this} */ this._init = function (arg) { s_init.call(m_this, arg); @@ -88,6 +132,7 @@ var vectorFeature = function (arg) { m_this.style(defaultStyle); m_this.dataTime().modified(); + return m_this; }; }; From 4cfe671910aaa472d2db32f41bd6afd6c4cd3b99 Mon Sep 17 00:00:00 2001 From: David Manthey Date: Mon, 26 Nov 2018 11:02:43 -0500 Subject: [PATCH 2/2] Remove a stray partial line. --- src/vectorFeature.js | 1 - 1 file changed, 1 deletion(-) diff --git a/src/vectorFeature.js b/src/vectorFeature.js index 5a7d1684e7..c9c8c5f541 100644 --- a/src/vectorFeature.js +++ b/src/vectorFeature.js @@ -8,7 +8,6 @@ var feature = require('./feature'); * @property {geo.vectorFeature.styleSpec} [style] Style object with default * style options. * @property {function|object} [origin={x: 0, y: 0, z: 0}] Origin accessor. - * @property {function */ /**