Update documentation for pointFeature.

This also touches documentation on util/clustering.js, though that could
use some refactoring so that clusters are computed in map gcs rather
than in feature gcs (usually interface gcs) and the cluster size is
given in simpler units (such as display pixels).

This fixes a number of trivial documentation issues in other files, too.

Also, improve documentation of position in line and polygon features.

src/d3/lineFeature.js

@@ -8,6 +8,7 @@ var lineFeature = require('../lineFeature');
  * @class
  * @alias geo.d3.lineFeature
  * @extends geo.lineFeature
+ * @extends geo.d3.object
  * @param {geo.lineFeature.spec} arg
  * @returns {geo.d3.lineFeature}
  */

src/d3/pointFeature.js

@@ -4,12 +4,13 @@ var pointFeature = require('../pointFeature');
 
 /**
  *
- * Create a new instance of pointFeature
+ * Create a new instance of d3.pointFeature.
  *
  * @class
  * @alias geo.d3.pointFeature
  * @extends geo.pointFeature
  * @extends geo.d3.object
+ * @param {geo.pointFeature.spec} arg
  * @returns {geo.d3.pointFeature}
  */
 var d3_pointFeature = function (arg) {
@@ -35,17 +36,20 @@ var d3_pointFeature = function (arg) {
       m_style = {};
 
   /**
-   * Initialize
+   * Initialize.
+   *
+   * @param {geo.pointFeature.spec} arg The feature specification.
+   * @returns {this}
    */
   this._init = function (arg) {
     s_init.call(m_this, arg);
     return m_this;
   };
 
   /**
-   * Build
+   * Build.  Create the necessary elements to render points.
    *
-   * @override
+   * @returns {this}
    */
   this._build = function () {
     var data = m_this.data(),
@@ -84,11 +88,10 @@ var d3_pointFeature = function (arg) {
     m_this.updateTime().modified();
     return m_this;
   };
-
   /**
-   * Update
+   * Update.  Rebuild if necessary.
    *
-   * @override
+   * @returns {this}
    */
   this._update = function () {
     s_update.call(m_this);

src/d3/uniqueID.js

@@ -2,9 +2,10 @@ var chars = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXTZabcdefghiklmnopqrstuvwxyz',
     strLength = 8;
 
 /**
- * Get a random string to use as a div ID
- * @function geo.d3.uniqueID
- * @returns {string}
+ * Get a random string to use as a div ID.
+ *
+ * @alias geo.d3.uniqueID
+ * @returns {string} A random ID string.
  */
 var uniqueID = function () {
   var strArray = [],

src/feature.js

@@ -405,6 +405,9 @@ var feature = function (arg) {
    * has a subfeature style, with `(subfeatureElement, subfeatureIndex,
    * dataElement, dataIndex)`.
    *
+   * See the feature's specification ({@link geo.feature.spec}) for available
+   * styles.
+   *
    * @param {string|object} [arg1] If `undefined`, return the current style
    *    object.  If a string and `arg2` is undefined, return the style
    *    associated with the specified key.  If a string and `arg2` is defined,

src/gl/lineFeature.js

@@ -376,7 +376,7 @@ var gl_lineFeature = function (arg) {
     return shader;
   }
 
- /**
+  /**
    * Create and style the data needed to render the lines.
    *
    * @param {boolean} onlyStyle if true, use the existing geoemtry and just

src/gl/pointFeature.js

@@ -4,11 +4,12 @@ var registerFeature = require('../registry').registerFeature;
 var pointFeature = require('../pointFeature');
 
 /**
- * Create a new instance of pointFeature
+ * Create a new instance of gl.pointFeature.
  *
  * @class
  * @alias geo.gl.pointFeature
  * @extends geo.pointFeature
+ * @param {geo.pointFeature.spec} arg
  * @returns {geo.gl.pointFeature}
  */
 var gl_pointFeature = function (arg) {
@@ -196,18 +197,39 @@ var gl_pointFeature = function (arg) {
 
   fragmentShaderSource = fragmentShaderSource.join('\n');
 
+  /**
+   * Create the vertex shader for points.
+   *
+   * @returns {vgl.shader}
+   */
   function createVertexShader() {
     var shader = new vgl.shader(vgl.GL.VERTEX_SHADER);
     shader.setShaderSource(vertexShaderSource);
     return shader;
   }
 
+  /**
+   * Create the fragment shader for points.
+   *
+   * @returns {vgl.shader}
+   */
   function createFragmentShader() {
     var shader = new vgl.shader(vgl.GL.FRAGMENT_SHADER);
     shader.setShaderSource(fragmentShaderSource);
     return shader;
   }
 
+  /**
+   * Given the current primitive shape and a basic size, return a set of
+   * vertices that can be used for a generic point.
+   *
+   * @param {number} x The base x coordinate.  Usually 0.
+   * @param {number} y The base y coordinate.  Usually 0.
+   * @param {number} w The base width.  Usually 1.
+   * @param {number} h The base height.  Usually 1.
+   * @returns {number[]} A flat array of vertices in the form of
+   *    `[x0, y0, x1, y1, ...]`.
+   */
   function pointPolygon(x, y, w, h) {
     var verts;
     switch (m_primitiveShape) {
@@ -240,6 +262,9 @@ var gl_pointFeature = function (arg) {
     return verts;
   }
 
+  /**
+   * Create and style the data needed to render the points.
+   */
   function createGLPoints() {
     // unit and associated data is not used when drawing sprite
     var i, j, numPts = m_this.data().length,
@@ -351,7 +376,7 @@ var gl_pointFeature = function (arg) {
   }
 
   /**
-   * Return list of actors
+   * Return list of vgl actorss used for rendering.
    *
    * @returns {vgl.actor[]}
    */
@@ -365,13 +390,33 @@ var gl_pointFeature = function (arg) {
   /**
    * Return the number of vertices used for each point.
    *
-   * @returns {Number}
+   * @returns {number}
    */
   this.verticesPerFeature = function () {
     var unit = pointPolygon(0, 0, 1, 1);
     return unit.length / 2;
   };
 
+  /**
+   * Set style(s) from array(s).  For each style, the array should have one
+   * value per data item.  The values are not converted or validated.  Color
+   * values should be {@link geo.geoColorObject}s.  If invalid values are given
+   * the behavior is undefined.
+   *   For some feature styles, if the first entry of an array is itself an
+   * array, then each entry of the array is expected to be an array, and values
+   * are used from these subarrays.  This allows a style to apply, for
+   * instance, per vertex of a data item rather than per data item.
+   *
+   * @param {string|object} keyOrObject Either the name of a single style or
+   *    an object where the keys are the names of styles and the values are
+   *    each arrays.
+   * @param {array} styleArray If keyOrObject is a string, an array of values
+   *    for the style.  If keyOrObject is an object, this parameter is ignored.
+   * @param {boolean} [refresh=false] `true` to redraw the feature when it has
+   *    been updated.  If an object with styles is passed, the redraw is only
+   *    done once.
+   * @returns {this}
+   */
   this.updateStyleFromArray = function (keyOrObject, styleArray, refresh) {
     var bufferedKeys = {
       fill: 'bool',
@@ -445,10 +490,11 @@ var gl_pointFeature = function (arg) {
     } else if (needsRender) {
       m_this.renderer()._render();
     }
+    return m_this;
   };
 
   /**
-   * Initialize
+   * Initialize.
    */
   this._init = function () {
     var prog = vgl.shaderProgram(),
@@ -547,9 +593,9 @@ var gl_pointFeature = function (arg) {
   };
 
   /**
-   * Build
+   * Build.  Create the necessary elements to render points.
    *
-   * @override
+   * @returns {this}
    */
   this._build = function () {
 
@@ -562,12 +608,13 @@ var gl_pointFeature = function (arg) {
     m_this.renderer().contextRenderer().addActor(m_actor);
     m_this.renderer().contextRenderer().render();
     m_this.buildTime().modified();
+    return m_this;
   };
 
   /**
-   * Update
+   * Update.  Rebuild if necessary.
    *
-   * @override
+   * @returns {this}
    */
   this._update = function () {
 
@@ -589,10 +636,11 @@ var gl_pointFeature = function (arg) {
     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);

src/lineFeature.js

@@ -8,8 +8,8 @@ var util = require('./util');
  * Line feature specification.
  *
  * @typedef {geo.feature.spec} geo.lineFeature.spec
- * @property {object|function} [position] Position of the data.  Default is
- *   (data).
+ * @property {geo.geoPosition|function} [position] Position of the data.
+ *   Default is (data).
  * @property {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
@@ -105,11 +105,12 @@ var lineFeature = function (arg) {
   /**
    * Get/Set position accessor.
    *
-   * @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.
+   * @param {geo.geoPosition|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 {geo.geoPosition|function|this} The current position or this
+   *    feature.
    */
   this.position = function (val) {
     if (val === undefined) {