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.
MODIFY
src/feature.js
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

MODIFY
src/gl/lineFeature.js
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}

MODIFY
src/lineFeature.js
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}
@@ -84,9 +85,11 @@ var lineFeature = function (arg) {
/**
* 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) {

MODIFY
src/polygonFeature.js
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) {

MODIFY
src/typedef.js
src/typedef.js
* @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
+ */

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.