Improve jsdocs for line features.
Also correct some minor issues with docs for the polygon feature.
MODIFY
src/canvas/lineFeature.js
src/canvas/lineFeature.js
@@ -3,11 +3,11 @@ var registerFeature = require('../registry').registerFeature;
var lineFeature = require('../lineFeature');
/**
- * Create a new instance of class lineFeature
+ * Create a new instance of class lineFeature.
*
* @class geo.canvas.lineFeature
* @extends geo.lineFeature
- * @extends geo.canvas.object
+ * @param {geo.lineFeature.spec} arg
* @returns {geo.canvas.lineFeature}
*/
var canvas_lineFeature = function (arg) {
@@ -29,9 +29,10 @@ var canvas_lineFeature = function (arg) {
/**
* Render the data on the canvas.
+ *
* @protected
* @param {object} context2d the canvas context to draw in.
- * @param {object} map the parent map object.
+ * @param {geo.map} map the parent map object.
*/
this._renderOnCanvas = function (context2d, map) {
var data = m_this.data(),

MODIFY
src/d3/lineFeature.js
src/d3/lineFeature.js
@@ -3,11 +3,11 @@ var registerFeature = require('../registry').registerFeature;
var lineFeature = require('../lineFeature');
/**
- * Create a new instance of class lineFeature
+ * Create a new instance of class lineFeature.
*
* @class geo.d3.lineFeature
* @extends geo.lineFeature
- * @extends geo.d3.object
+ * @param {geo.lineFeature.spec} arg
* @returns {geo.d3.lineFeature}
*/
var d3_lineFeature = function (arg) {
@@ -35,7 +35,10 @@ var d3_lineFeature = function (arg) {
s_update = this._update;
/**
- * Initialize
+ * Initialize.
+ *
+ * @param {geo.lineFeature.spec} arg The feature specification.
+ * @returns {this}
*/
this._init = function (arg) {
s_init.call(m_this, arg);
@@ -43,9 +46,9 @@ var d3_lineFeature = function (arg) {
};
/**
- * Build
+ * Build. Create the necessary elements to render lines.
*
- * @override
+ * @returns {this}
*/
this._build = function () {
var data = m_this.data() || [],
@@ -109,9 +112,9 @@ var d3_lineFeature = function (arg) {
};
/**
- * Update
+ * Update. Rebuild if necessary.
*
- * @override
+ * @returns {this}
*/
this._update = function () {
s_update.call(m_this);

MODIFY
src/gl/lineFeature.js
src/gl/lineFeature.js
@@ -34,10 +34,11 @@ var flagsDebug = { // uses 1 bit
};
/**
- * Create a new instance of lineFeature
+ * Create a new instance of lineFeature.
*
* @class geo.gl.lineFeature
* @extends geo.lineFeature
+ * @param {geo.lineFeature.spec} arg
* @returns {geo.gl.lineFeature}
*/
var gl_lineFeature = function (arg) {
@@ -72,6 +73,11 @@ var gl_lineFeature = function (arg) {
s_init = this._init,
s_update = this._update;
+ /**
+ * Create the vertex shader for lines.
+ *
+ * @returns {vgl.shader}
+ */
function createVertexShader() {
var vertexShaderSource = [
'#ifdef GL_ES',
@@ -244,6 +250,14 @@ var gl_lineFeature = function (arg) {
return shader;
}
+ /**
+ * Create the fragment shader for lines.
+ *
+ * @param {boolean} [allowDebug] If truthy, include code that can render
+ * in debug mode. This is mildly less efficient, even if debugging is
+ * not turned on.
+ * @returns {vgl.shader}
+ */
function createFragmentShader(allowDebug) {
var fragmentShaderSource = [
'#ifdef GL_ES',
@@ -349,6 +363,9 @@ var gl_lineFeature = function (arg) {
return shader;
}
+ /**
+ * Create and style the data needed to render the lines.
+ */
function createGLLines() {
var data = m_this.data(),
i, j, k, v, v2, lidx,
@@ -533,12 +550,14 @@ var gl_lineFeature = function (arg) {
}
/**
- * Return the arrangement of vertices used for each line segment.
+ * Return the arrangement of vertices used for each line segment. Each line
+ * is rendered by two triangles. This reports how the vertices of those
+ * triangles are arranged. Each entry is a triple: the line-end number, the
+ * vertex use, and the side of the line that the vertex is on.
*
- * @returns {Number}
+ * @returns {array[]}
*/
this.featureVertices = function () {
- // return [[0, -1], [0, 1], [1, -1], [1, 1], [1, -1], [0, 1]];
return [[0, 'corner', -1], [0, 'near', 1], [1, 'far', -1],
[1, 'corner', 1], [1, 'near', -1], [0, 'far', 1]];
};
@@ -546,14 +565,17 @@ var gl_lineFeature = function (arg) {
/**
* Return the number of vertices used for each line segment.
*
- * @returns {Number}
+ * @returns {number}
*/
this.verticesPerFeature = function () {
return m_this.featureVertices().length;
};
/**
- * Initialize
+ * Initialize.
+ *
+ * @param {geo.lineFeature.spec} arg The feature specification.
+ * @returns {this}
*/
this._init = function (arg) {
var prog = vgl.shaderProgram(),
@@ -640,10 +662,11 @@ var gl_lineFeature = function (arg) {
geom.addSource(flagsData);
geom.addPrimitive(triangles);
m_mapper.setGeometryData(geom);
+ return m_this;
};
/**
- * Return list of actors
+ * Return list of vgl actorss used for rendering.
*
* @returns {vgl.actor[]}
*/
@@ -655,9 +678,9 @@ var gl_lineFeature = function (arg) {
};
/**
- * Build
+ * Build. Create the necessary elements to render lines.
*
- * @override
+ * @returns {this}
*/
this._build = function () {
createGLLines();
@@ -666,12 +689,13 @@ var gl_lineFeature = function (arg) {
m_this.renderer().contextRenderer().addActor(m_actor);
}
m_this.buildTime().modified();
+ return m_this;
};
/**
- * Update
+ * Update. Rebuild if necessary.
*
- * @override
+ * @returns {this}
*/
this._update = function () {
s_update.call(m_this);
@@ -687,10 +711,11 @@ var gl_lineFeature = function (arg) {
m_actor.setVisible(m_this.visible());
m_actor.material().setBinNumber(m_this.bin());
m_this.updateTime().modified();
+ return m_this;
};
/**
- * Destroy
+ * Destroy. Free used resources.
*/
this._exit = function () {
m_this.renderer().contextRenderer().removeActor(m_actor);
@@ -704,7 +729,6 @@ var gl_lineFeature = function (arg) {
inherit(gl_lineFeature, lineFeature);
-// Now register it
var capabilities = {};
capabilities[lineFeature.capabilities.basic] = true;
capabilities[lineFeature.capabilities.multicolor] = true;

MODIFY
src/gl/polygonFeature.js
src/gl/polygonFeature.js
@@ -80,7 +80,7 @@ var gl_polygonFeature = function (arg) {
}
/**
- * Create and style the triangles need to render the polygons.
+ * Create and style the triangles needed to render the polygons.
*
* There are several optimizations to do less work when possible. If only
* styles have changed, the triangulation is not recomputed, nor is the
@@ -315,7 +315,6 @@ var gl_polygonFeature = function (arg) {
* @override
*/
this._build = function () {
-
createGLPolygons(m_this.dataTime().getMTime() < m_this.buildTime().getMTime() && m_geometry);
if (!m_this.renderer().contextRenderer().hasActor(m_actor)) {

MODIFY
src/lineFeature.js
src/lineFeature.js
@@ -4,48 +4,51 @@ var timestamp = require('./timestamp');
var transform = require('./transform');
/**
- * Create a new instance of class lineFeature
+ * Line feature specification.
*
- * @class geo.lineFeature
- * @extends geo.feature
- * @param {Object|Function} [arg.position] Position of the data. Default is
+ * @typedef {geo.feature.spec} geo.lineFeature.spec
+ * @param {object|Function} [position] Position of the data. Default is
* (data).
- * @param {Object|Function} [arg.line] Lines from the data. Default is (data).
+ * @param {object|Function} [line] Lines from the data. Default is (data).
* Typically, the data is an array of lines, each of which is an array of
* points. Only lines that have at least two points are rendered. The
- * position function is called for each point as position(linePoint,
- * pointIndex, lineEntry, lineEntryIndex).
- * @param {boolean} [arg.selectionAPI=false] True to send selection events on
- * mouse move, click, etc.
- * @param {boolean} [arg.visible=true] True to show this feature.
- * @param {Object} [arg.style] Style object with default style options.
- * @param {Object|Function} [arg.style.strokeColor] Color to stroke each
- * line. The color can vary by point. Colors can be css names or hex
- * values, or an object with r, g, b on a [0-1] scale.
- * @param {number|Function} [arg.style.strokeOpacity] Opacity for each line
+ * position function is called for each point as `position(linePoint,
+ * pointIndex, lineEntry, lineEntryIndex)`.
+ * @param {object} [style] Style object with default style options.
+ * @param {geo.geoColor|Function} [style.strokeColor] Color to stroke each
+ * line. The color can vary by point.
+ * @param {number|Function} [style.strokeOpacity] Opacity for each line
* stroke. The opacity can vary by point. Opacity is on a [0-1] scale.
- * @param {number|Function} [arg.style.strokeWidth] The weight of the line
+ * @param {number|Function} [style.strokeWidth] The weight of the line
* stroke in pixels. The width can vary by point.
- * @param {number|Function} [arg.style.strokeOffset] This is a value from -1
+ * @param {number|Function} [style.strokeOffset] This is a value from -1
* (left) to 1 (right), with 0 being centered. This can vary by point.
- * @param {string|Function} [arg.style.lineCap] One of 'butt' (default),
- * 'square', or 'round'. This can vary by point.
- * @param {string|Function} [arg.style.lineJoin] One of 'miter' (default),
- * 'bevel', 'round', or 'miter-clip'. This can vary by point.
- * @param {number|Function} [arg.style.closed] If true and the renderer
+ * @param {string|Function} [style.lineCap='butt'] One of 'butt', 'square', or
+ * 'round'. This can vary by point.
+ * @param {string|Function} [style.lineJoin='miter'] One of 'miter', 'bevel',
+ * 'round', or 'miter-clip'. This can vary by point.
+ * @param {boolean|Function} [style.closed=false] If true and the renderer
* supports it, connect the first and last points of a line if the line has
* more than two points. This applies per line (if a function, it is called
- * with (lineEntry, lineEntryIndex).
- * @param {number|Function} [arg.style.miterLimit] For lines of more than two
- * segments that are mitered, if the miter length exceeds the strokeWidth
+ * with `(lineEntry, lineEntryIndex)`.
+ * @param {number|Function} [style.miterLimit=10] For lines of more than two
+ * segments that are mitered, if the miter length exceeds the `strokeWidth`
* divided by the sine of half the angle between segments, then a bevel join
* is used instead. This is a single value that applies to all lines. If a
- * function, it is called with (data).
- * @param {string|Function} [arg.style.antialiasing] Antialiasing distance in
+ * function, it is called with `(data)`.
+ * @param {number|Function} [style.antialiasing] Antialiasing distance in
* pixels. Values must be non-negative. A value greater than 1 will produce
* a visible gradient. This is a single value that applies to all lines.
- * @param {string|Function} [arg.style.debug] If 'debug', render lines in debug
+ * @param {string|Function} [style.debug] If 'debug', render lines in debug
* mode. This is a single value that applies to all lines.
+ */
+
+/**
+ * Create a new instance of class lineFeature.
+ *
+ * @class geo.lineFeature
+ * @extends geo.feature
+ * @param {geo.lineFeature.spec} arg
* @returns {geo.lineFeature}
*/
var lineFeature = function (arg) {
@@ -78,9 +81,11 @@ var lineFeature = function (arg) {
};
/**
- * Get/Set line accessor
+ * Get/set lineaccessor.
*
- * @returns {geo.pointFeature}
+ * @param {object} [val] if specified, use this for the line accessor
+ * and return the feature. If not specified, return the current line.
+ * @returns {object|this} The current line or this feature.
*/
this.line = function (val) {
if (val === undefined) {
@@ -94,9 +99,12 @@ var lineFeature = function (arg) {
};
/**
- * Get/Set position accessor
+ * Get/Set position accessor.
*
- * @returns {geo.pointFeature}
+ * @param {object} [val] if specified, use this for the position accessor
+ * and return the feature. If not specified, return the current
+ * position.
+ * @returns {object|this} The current position or this feature.
*/
this.position = function (val) {
if (val === undefined) {
@@ -110,12 +118,19 @@ var lineFeature = function (arg) {
};
/**
- * Cache information needed for point searches.
+ * Cache information needed for point searches. The point search
+ * information record is an array with one entry per line, each entry of
+ * which is an array with one entry per line segment. These each contain
+ * an object with the end coordinates (`u`, `v`) of the segment in map gcs
+ * coordinates and the square of the maximum half-width that needs to be
+ * considered for the line (`r2`).
+ *
+ * @returns {object} The point search information record.
*/
this._updatePointSearchInfo = function () {
if (m_pointSearchTime.getMTime() >= m_this.dataTime().getMTime() &&
m_pointSearchTime.getMTime() >= m_this.getMTime()) {
- return;
+ return m_pointSearchInfo;
}
m_pointSearchTime.modified();
m_pointSearchInfo = [];
@@ -156,16 +171,18 @@ var lineFeature = function (arg) {
};
/**
- * Returns an array of datum indices that contain the given point.
- * This is a slow implementation with runtime order of the number of
- * vertices. A point is considered on a line segment if it is close to the
- * line or either end point. Closeness is based on the maximum width of the
- * line segement, and is ceil(maxwidth / 2) + 2 pixels. This means that
- * corner extensions due to mitering may be outside of the selection area and
- * that variable width lines will have a greater selection region than their
- * visual size at the narrow end.
+ * Returns an array of datum indices that contain the given point. This is a
+ * slow implementation with runtime order of the number of vertices. A point
+ * is considered on a line segment if it is close to the line or either end
+ * point. Closeness is based on the maximum width of the line segement, and
+ * is `ceil(maxwidth / 2) + 2` pixels. This means that corner extensions
+ * due to mitering may be outside of the selection area and that variable-
+ * width lines will have a greater selection region than their visual size at
+ * the narrow end.
*
* @param {geo.geoPosition} p point to search for in map interface gcs.
+ * @returns {object} An object with `index`: a list of line indices, and
+ * `found`: a list of quads that contain the specified coordinate.
*/
this.pointSearch = function (p) {
var data = m_this.data(), indices = [], found = [];
@@ -222,7 +239,15 @@ var lineFeature = function (arg) {
};
/**
- * Returns an array of line indices that are contained in the given box.
+ * Search for lines contained within a rectangilar region.
+ *
+ * @param {geo.geoPosition} lowerLeft Lower-left corner in gcs coordinates.
+ * @param {geo.geoPosition} upperRight Upper-right corner in gcs coordinates.
+ * @param {object} [opts] Additional search options.
+ * @param {boolean} [opts.partial=false] If truthy, include lines that are
+ * partially in the box, otherwise only include lines that are fully
+ * within the region.
+ * @returns {number[]} A list of line indices that are in the box region.
*/
this.boxSearch = function (lowerLeft, upperRight, opts) {
var pos = m_this.position(),
@@ -256,7 +281,10 @@ var lineFeature = function (arg) {
};
/**
- * Initialize
+ * Initialize.
+ *
+ * @param {geo.lineFeature.spec} arg The feature specification.
+ * @returns {this}
*/
this._init = function (arg) {
arg = arg || {};
@@ -290,6 +318,7 @@ var lineFeature = function (arg) {
m_this.style(defaultStyle);
m_this.dataTime().modified();
+ return m_this;
};
this._init(arg);
@@ -297,11 +326,12 @@ var lineFeature = function (arg) {
};
/**
- * Create a lineFeature from an object.
+ * Create a lineFeature.
+ *
* @see {@link geo.feature.create}
* @param {geo.layer} layer The layer to add the feature to
- * @param {geo.lineFeature.spec} spec The object specification
- * @returns {geo.lineFeature|null}
+ * @param {geo.lineFeature.spec} spec The feature specification
+ * @returns {geo.lineFeature|null} The created feature or `null` for failure.
*/
lineFeature.create = function (layer, spec) {
'use strict';

MODIFY
src/polygonFeature.js
src/polygonFeature.js
@@ -19,16 +19,14 @@ var transform = require('./transform');
* @param {object} [style] Style object with default style options.
* @param {boolean|Function} [style.fill] True to fill polygon. Defaults to
* true.
- * @param {object|Function} [style.fillColor] Color to fill each polygon. The
- * color can vary by vertex. Colors can be css names or hex values, or an
- * object with r, g, b on a [0-1] scale.
+ * @param {geo.geoColor|Function} [style.fillColor] Color to fill each polygon.
+ * The color can vary by vertex.
* @param {number|Function} [style.fillOpacity] Opacity for each polygon. The
* opacity can vary by vertex. Opacity is on a [0-1] scale.
* @param {boolean|Function} [style.stroke] True to stroke polygon. Defaults
* to false.
- * @param {object|Function} [style.strokeColor] Color to stroke each polygon.
- * The color can vary by vertex. Colors can be css names or hex values, or
- * an object with r, g, b on a [0-1] scale.
+ * @param {geo.geoColor|Function} [style.strokeColor] Color to stroke each
+ * polygon. The color can vary by vertex.
* @param {number|Function} [style.strokeOpacity] Opacity for each polygon
* stroke. The opacity can vary by vertex. Opacity is on a [0-1] scale.
* @param {number|Function} [style.strokeWidth] The weight of the polygon
@@ -215,8 +213,8 @@ var polygonFeature = function (arg) {
*
* @param {geo.geoPosition} coordinate point to search for in map interface
* gcs.
- * @returns {object} An object with `index`: a list of quad indices, and
- * `found`: a list of quads that contain the specified coordinate.
+ * @returns {object} An object with `index`: a list of polygon indices, and
+ * `found`: a list of polygons that contain the specified coordinate.
*/
this.pointSearch = function (coordinate) {
var found = [], indices = [], irecord = {}, data = m_this.data(),

Improve jsdocs for line features.

Also correct some minor issues with docs for the polygon feature.