Improve polygon and line documentation.

This should make it clearer what the position, line, and polygon
accessors do.  It also explicitly defines a polygon data type.

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/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/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 specified, use this for the line
+   *    accessor and return the feature.  If not specified, return the current
+   *    line.  If a function, this is passed `(dataElement, dataIndex)` and
+   *    returns an array of vertex elements.
+   * @returns {object|function|this} The current line 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 specified, use this for the position
+   *    accessor and return the feature.  If not specified, return the current
+   *    position.  If a function, 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) {

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,11 @@ 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 specified, use this for the polygon
+   *    accessor and return the feature.  If not specified, return the current
+   *    polygon.  If a function, this is passed `(dataElement, dataIndex)` and
+   *    returns a `geo.polygon`.
+   * @returns {object|function|this} The current polygon or this feature.
    */
   this.polygon = function (val) {
     if (val === undefined) {
@@ -207,9 +204,10 @@ var polygonFeature = function (arg) {
   /**
    * Get/Set position accessor.
    *
-   * @param {object} [val] if specified, use this for the position accessor
+   * @param {object} [val] If specified, use this for the position accessor
    *    and return the feature.  If not specified, return the current
-   *    position.
+   *    position.  If a function, this is called with `(vertexElement,
+   *    vertexIndex, dataElement, dataIndex)`.
    * @returns {object|this} The current position or this feature.
    */
   this.position = function (val) {

src/typedef.js

@@ -271,3 +271,27 @@
  * @property {number} [a] The opacity on a scale of [0-1].  If unspecified and
  *      used, it should be treated as 1.
  */
+
+/**
+ * Polygon as a flat array.  An array of vertices.  The polygon has no holes.
+ * The first and last point of may be the same.
+ *
+ * @typedef {geo.geoPosition[]} geo.polygonFlat
+ */
+
+/**
+ * Polygon as a object.  The polygon may have holes.
+ *
+ * @typedef {object} geo.polygonObject
+ * @property {geo.geoPosition[]} outer An array of vertices defining the
+ *   outside of the polygon.  The first and last point of may be the same.
+ * @property {Array.<geo.geoPosition[]>} [inner] An array of holes, each of
+ *   which is an array of vertices.  The first and last point of may be the
+ *  same.
+ */
+
+/**
+ * Polygon.
+ *
+ * @typedef {geo.polygonFlat|geo.polygonObject} geo.polygon
+ */