Merge pull request #858 from OpenGeoscience/update-point-docs

Update documentation for pointFeature.

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 are {@link geo.geoColorObject} objects.  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) {