Merge pull request #824 from OpenGeoscience/polygon-and-line-docs

Improve polygon and line documentation.

src/canvas/canvasRenderer.js

@@ -5,7 +5,8 @@ var renderer = require('../renderer');
 /**
  * Create a new instance of class canvasRenderer.
  *
- * @class geo.canvas.renderer
+ * @class
+ * @alias geo.canvas.renderer
  * @extends geo.renderer
  * @param {object} arg Options for the renderer.
  * @param {geo.layer} [arg.layer] Layer associated with the renderer.

src/canvas/heatmapFeature.js

@@ -8,7 +8,8 @@ var timestamp = require('../timestamp');
  * Inspired from
  *    https://github.com/mourner/simpleheat/blob/gh-pages/simpleheat.js
  *
- * @class geo.canvas.heatmapFeature
+ * @class
+ * @alias geo.canvas.heatmapFeature
  * @param {Object} arg Options object
  * @extends geo.heatmapFeature
  * @returns {canvas_heatmapFeature}

src/canvas/lineFeature.js

@@ -5,7 +5,8 @@ var lineFeature = require('../lineFeature');
 /**
  * Create a new instance of class lineFeature.
  *
- * @class geo.canvas.lineFeature
+ * @class
+ * @alias geo.canvas.lineFeature
  * @extends geo.lineFeature
  * @param {geo.lineFeature.spec} arg
  * @returns {geo.canvas.lineFeature}

src/canvas/pixelmapFeature.js

@@ -5,7 +5,8 @@ var pixelmapFeature = require('../pixelmapFeature');
 /**
  * Create a new instance of class pixelmapFeature
  *
- * @class geo.canvas.pixelmapFeature
+ * @class
+ * @alias geo.canvas.pixelmapFeature
  * @param {Object} arg Options object
  * @extends geo.pixelmapFeature
  * @returns {canvas_pixelmapFeature}

src/canvas/quadFeature.js

@@ -6,7 +6,8 @@ var util = require('../util');
 /**
  * Create a new instance of class quadFeature.
  *
- * @class geo.canvas.quadFeature
+ * @class
+ * @alias geo.canvas.quadFeature
  * @param {geo.quadFeature.spec} arg Options object.
  * @extends geo.quadFeature
  * @returns {geo.canvas.quadFeature}

src/choroplethFeature.js

@@ -4,7 +4,8 @@ var feature = require('./feature');
 /**
  * Create a new instance of class choroplethFeature
  *
- * @class geo.choroplethFeature
+ * @class
+ * @alias geo.choroplethFeature
  * @param {Object} arg Options object
  * @extends geo.feature
  * @param {Array} [colorRange] Color lookup table for

src/d3/d3Renderer.js

@@ -5,7 +5,8 @@ var renderer = require('../renderer');
 /**
  * Create a new instance of class d3Renderer.
  *
- * @class geo.d3.renderer
+ * @class
+ * @alias geo.d3.renderer
  * @extends geo.renderer
  * @param {object} arg Options for the renderer.
  * @param {geo.layer} [arg.layer] Layer associated with the renderer.

src/d3/graphFeature.js

@@ -3,7 +3,8 @@ var registerFeature = require('../registry').registerFeature;
 var graphFeature = require('../graphFeature');
 
 /**
- * @class geo.d3.graphFeature
+ * @class
+ * @alias geo.d3.graphFeature
  * @extends geo.graphFeature
  */
 var d3_graphFeature = function (arg) {

src/d3/lineFeature.js

@@ -5,7 +5,8 @@ var lineFeature = require('../lineFeature');
 /**
  * Create a new instance of class lineFeature.
  *
- * @class geo.d3.lineFeature
+ * @class
+ * @alias geo.d3.lineFeature
  * @extends geo.lineFeature
  * @param {geo.lineFeature.spec} arg
  * @returns {geo.d3.lineFeature}

src/d3/pathFeature.js

@@ -5,7 +5,8 @@ var pathFeature = require('../pathFeature');
 /**
  * Create a new instance of class pathFeature
  *
- * @class geo.d3.pathFeature
+ * @class
+ * @alias geo.d3.pathFeature
  * @extends geo.pathFeature
  * @extends geo.d3.object
  * @returns {geo.d3.pathFeature}

src/d3/pointFeature.js

@@ -6,7 +6,8 @@ var pointFeature = require('../pointFeature');
  *
  * Create a new instance of pointFeature
  *
- * @class geo.d3.pointFeature
+ * @class
+ * @alias geo.d3.pointFeature
  * @extends geo.pointFeature
  * @extends geo.d3.object
  * @returns {geo.d3.pointFeature}

src/d3/quadFeature.js

@@ -5,7 +5,8 @@ var quadFeature = require('../quadFeature');
 /**
  * Create a new instance of class quadFeature.
  *
- * @class geo.d3.quadFeature
+ * @class
+ * @alias geo.d3.quadFeature
  * @param {geo.quadFeature.spec} arg Options object.
  * @extends geo.quadFeature
  * @returns {geo.d3.quadFeature}

src/d3/vectorFeature.js

@@ -5,7 +5,8 @@ var vectorFeature = require('../vectorFeature');
 /**
  * Create a new instance of vectorFeature
  *
- * @class geo.d3.vectorFeature
+ * @class
+ * @alias geo.d3.vectorFeature
  * @extends geo.vectorFeature
  * @extends geo.d3.object
  * @returns {geo.d3.vectorFeature}

src/domRenderer.js

@@ -5,7 +5,8 @@ var registerRenderer = require('./registry').registerRenderer;
 /**
  * Create a new instance of class domRenderer.
  *
- * @class geo.domRenderer
+ * @class
+ * @alias geo.domRenderer
  * @extends geo.renderer
  * @param {object} arg Options for the renderer.
  * @param {geo.layer} [arg.layer] Layer associated with the renderer.

src/feature.js

@@ -399,7 +399,11 @@ var feature = function (arg) {
   };
 
   /**
-   * Get/Set style used by the feature.
+   * Get/Set style used by the feature.  Styles can be constant values or
+   * functions.  If a function, the style is typically called with parameters
+   * such as `(dataElement, dataIndex)` or, if the specific style of a feature
+   * has a subfeature style, with `(subfeatureElement, subfeatureIndex,
+   * dataElement, dataIndex)`.
    *
    * @param {string|object} [arg1] If `undefined`, return the current style
    *    object.  If a string and `arg2` is undefined, return the style

src/fileReader.js

@@ -5,7 +5,8 @@ var object = require('./object');
 /**
  * Create a new instance of class fileReader
  *
- * @class geo.fileReader
+ * @class
+ * @alias geo.fileReader
  * @extends geo.object
  * @returns {geo.fileReader}
  */

src/gl/choroplethFeature.js

@@ -5,7 +5,8 @@ var choroplethFeature = require('../choroplethFeature');
 /**
  * Create a new instance of choroplethFeature
  *
- * @class geo.gl.choroplethFeature
+ * @class
+ * @alias geo.gl.choroplethFeature
  * @extends geo.choroplethFeature
  * @returns {geo.gl.choroplethFeature}
  */

src/gl/contourFeature.js

@@ -5,7 +5,8 @@ var contourFeature = require('../contourFeature');
 /**
  * Create a new instance of contourFeature
  *
- * @class geo.gl.contourFeature
+ * @class
+ * @alias geo.gl.contourFeature
  * @extends geo.contourFeature
  * @returns {geo.gl.contourFeature}
  */

src/gl/lineFeature.js

@@ -36,7 +36,8 @@ var flagsDebug = {  // uses 1 bit
 /**
  * Create a new instance of lineFeature.
  *
- * @class geo.gl.lineFeature
+ * @class
+ * @alias geo.gl.lineFeature
  * @extends geo.lineFeature
  * @param {geo.lineFeature.spec} arg
  * @returns {geo.gl.lineFeature}

src/gl/pointFeature.js

@@ -6,7 +6,8 @@ var pointFeature = require('../pointFeature');
 /**
  * Create a new instance of pointFeature
  *
- * @class geo.gl.pointFeature
+ * @class
+ * @alias geo.gl.pointFeature
  * @extends geo.pointFeature
  * @returns {geo.gl.pointFeature}
  */

src/gl/quadFeature.js

@@ -5,7 +5,8 @@ var quadFeature = require('../quadFeature');
 /**
  * Create a new instance of class quadFeature.
  *
- * @class geo.gl.quadFeature
+ * @class
+ * @alias geo.gl.quadFeature
  * @param {geo.quadFeature.spec} arg Options object.
  * @extends geo.quadFeature
  * @returns {geo.gl.quadFeature}

src/gl/vglRenderer.js

@@ -5,7 +5,8 @@ var renderer = require('../renderer');
 /**
  * Create a new instance of class vglRenderer.
  *
- * @class geo.gl.vglRenderer
+ * @class
+ * @alias geo.gl.vglRenderer
  * @extends geo.renderer
  * @param {object} arg Options for the renderer.
  * @param {geo.layer} [arg.layer] Layer associated with the renderer.

src/graphFeature.js

@@ -4,7 +4,8 @@ var feature = require('./feature');
 /**
  * Create a new instance of class graphFeature
  *
- * @class geo.graphFeature
+ * @class
+ * @alias geo.graphFeature
  * @extends geo.feature
  * @returns {geo.graphFeature}
  */

src/heatmapFeature.js

@@ -6,7 +6,8 @@ var transform = require('./transform');
 /**
  * Create a new instance of class heatmapFeature
  *
- * @class geo.heatmapFeature
+ * @class
+ * @alias geo.heatmapFeature
  * @param {Object} arg Options object
  * @extends geo.feature
  * @param {Object|Function} [position] Position of the data.  Default is

src/lineFeature.js

@@ -47,7 +47,8 @@ var util = require('./util');
 /**
  * Create a new instance of class lineFeature.
  *
- * @class geo.lineFeature
+ * @class
+ * @alias geo.lineFeature
  * @extends geo.feature
  * @param {geo.lineFeature.spec} arg
  * @returns {geo.lineFeature}
@@ -82,11 +83,13 @@ var lineFeature = function (arg) {
   };
 
   /**
-   * Get/set lineaccessor.
+   * Get/set line accessor.
    *
-   * @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.
+   * @param {object|function} [val] If not specified, return the current line
+   *    accessor.  If specified, use this for the line accessor and return
+   *    `this`.  If a function is given, the function is passed `(dataElement,
+   *    dataIndex)` and returns an array of vertex elements.
+   * @returns {object|function|this} The current line accessor or this feature.
    */
   this.line = function (val) {
     if (val === undefined) {
@@ -102,10 +105,11 @@ var lineFeature = function (arg) {
   /**
    * Get/Set position accessor.
    *
-   * @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.
+   * @param {object|function} [val] If not specified, return the current
+   *    position accessor.  If specified, use this for the position accessor
+   *    and return `this`.  If a function is given, this is called with
+   *    `(vertexElement, vertexIndex, dataElement, dataIndex)`.
+   * @returns {object|function|this} The current position or this feature.
    */
   this.position = function (val) {
     if (val === undefined) {
@@ -259,7 +263,7 @@ var lineFeature = function (arg) {
   };
 
   /**
-   * Take a set of data, reduce the number of vertices per linen using the
+   * Take a set of data, reduce the number of vertices per line using the
    * Ramer–Douglas–Peucker algorithm, and use the result as the new data.
    * This changes the instance's data, the position accessor, and the line
    * accessor.

src/pathFeature.js

@@ -5,7 +5,8 @@ var feature = require('./feature');
 /**
  * Create a new instance of class pathFeature
  *
- * @class geo.pathFeature
+ * @class
+ * @alias geo.pathFeature
  * @extends geo.feature
  * @returns {geo.pathFeature}
  */

src/pixelmapFeature.js

@@ -7,7 +7,8 @@ var util = require('./util');
 /**
  * Create a new instance of class imagemapFeature
  *
- * @class geo.pixelmapFeature
+ * @class
+ * @alias geo.pixelmapFeature
  * @param {Object} arg Options object
  * @extends geo.feature
  * @param {Object|Function|HTMLImageElement} [url] URL of a pixel map or an

src/pointFeature.js

@@ -4,7 +4,8 @@ var feature = require('./feature');
 /**
  * Create a new instance of class pointFeature
  *
- * @class geo.pointFeature
+ * @class
+ * @alias geo.pointFeature
  * @param {object} arg Options object
  * @param {boolean} arg.clustering Enable point clustering
  * @extends geo.feature

src/polygonFeature.js

@@ -9,13 +9,8 @@ var transform = require('./transform');
  * @typedef {geo.feature.spec} geo.polygonFeature.spec
  * @property {object|function} [position] Position of the data.  Default is
  *   (data).
- * @property {object|function} [polygon] Polygons from the data.  Default is
- *   (data).  Typically, the data is an array of polygons, each of which is of
- *   the form {outer: [(coordinates)], inner: [[(coordinates of first hole)],
- *   [(coordinates of second hole)], ...]}.  The inner record is optional.
- *   Alternately, if there are no holes, a polygon can just be an array of
- *   coordinates in the form of geo.geoPosition.  The first and last point of
- *   each polygon may be the same.
+ * @property {geo.polygon|function} [polygon] Polygons from the data.  Default
+ *   (data).
  * @property {object} [style] Style object with default style options.
  * @property {boolean|function} [style.fill=true] True to fill polygon.
  * @property {geo.geoColor|function} [style.fillColor] Color to fill each
@@ -105,8 +100,8 @@ var polygonFeature = function (arg) {
    *    get the position of each vertex.
    * @param {function} [polyFunc=this.style.get('polygon')] The function to
    *    get each polygon.
-   * @returns {object[]} An array of polygon positions.  Each has `outer` and
-   *    `inner` if it has any coordinates, or is undefined.
+   * @returns {geo.polygonObject[]} An array of polygon positions.  Each has
+   *    `outer` and `inner` if it has any coordinates, or is `undefined`.
    */
   function getCoordinates(data, posFunc, polyFunc) {
     data = data || m_this.data();
@@ -154,8 +149,8 @@ var polygonFeature = function (arg) {
   /**
    * Get the set of normalized polygon coordinates.
    *
-   * @returns {object[]} An array of polygon positions.  Each has `outer` and
-   *    `inner` if it has any coordinates, or is undefined.
+   * @returns {geo.polygonObject[]} An array of polygon positions.  Each has
+   *    `outer` and `inner` if it has any coordinates, or is `undefined`.
    */
   this.polygonCoordinates = function () {
     return m_coordinates;
@@ -188,9 +183,12 @@ var polygonFeature = function (arg) {
   /**
    * Get/set polygon accessor.
    *
-   * @param {object} [val] if specified, use this for the polygon accessor
-   *    and return the feature.  If not specified, return the current polygon.
-   * @returns {object|this} The current polygon or this feature.
+   * @param {object|function} [val] If not specified, return the current
+   *    polygon accessor.  If specified, use this for the polygon accessor and
+   *    return `this`.  If a function is given, the function is passed
+   *    `(dataElement, dataIndex)` and returns a `geo.polygon`.
+   * @returns {object|function|this} The current polygon accessor or this
+   *    feature.
    */
   this.polygon = function (val) {
     if (val === undefined) {
@@ -207,9 +205,10 @@ var polygonFeature = function (arg) {
   /**
    * Get/Set position accessor.
    *
-   * @param {object} [val] if specified, use this for the position accessor
-   *    and return the feature.  If not specified, return the current
-   *    position.
+   * @param {object|function} [val] If not specified, return the current
+   *    position accessor.  If specified, use this for the position accessor
+   *    and return `this`.  If a function is given, this is called with
+   *    `(vertexElement, vertexIndex, dataElement, dataIndex)`.
    * @returns {object|this} The current position or this feature.
    */
   this.position = function (val) {