From e6941220abda7cc3d43e650017630d11f8a0e570 Mon Sep 17 00:00:00 2001
From: David Manthey <david.manthey@kitware.com>
Date: Tue, 6 Nov 2018 14:30:04 -0500
Subject: [PATCH] Fix jsdocs for the path feature.

This also normalizes some of the arguments to make it more like other
features (for instance, actually using the position accessor).
---
 src/d3/pathFeature.js | 32 ++++++++--------------
 src/pathFeature.js    | 64 +++++++++++++++++++++++++++++++------------
 2 files changed, 57 insertions(+), 39 deletions(-)

diff --git a/src/d3/pathFeature.js b/src/d3/pathFeature.js
index e0bb1e2388..a5460ece2f 100644
--- a/src/d3/pathFeature.js
+++ b/src/d3/pathFeature.js
@@ -3,12 +3,13 @@ var registerFeature = require('../registry').registerFeature;
 var pathFeature = require('../pathFeature');
 
 /**
- * Create a new instance of class pathFeature
+ * Create a new instance of class geo.d3.pathFeature.
  *
  * @class
  * @alias geo.d3.pathFeature
  * @extends geo.pathFeature
  * @extends geo.d3.object
+ * @param {geo.pathFeature.spec} arg
  * @returns {geo.d3.pathFeature}
  */
 var d3_pathFeature = function (arg) {
@@ -26,11 +27,7 @@ var d3_pathFeature = function (arg) {
   pathFeature.call(this, arg);
   object.call(this);
 
-  /**
-   * @private
-   */
   var m_this = this,
-      s_init = this._init,
       m_buildTime = timestamp(),
       s_update = this._update,
       m_style = {};
@@ -38,21 +35,14 @@ var d3_pathFeature = function (arg) {
   m_style.style = {};
 
   /**
-   * Initialize
-   */
-  this._init = function (arg) {
-    s_init.call(m_this, arg);
-    return m_this;
-  };
-
-  /**
-   * Build
+   * Build.
    *
-   * @override
+   * @returns {this}
    */
   this._build = function () {
     var data = m_this.data() || [],
         s_style = m_this.style(),
+        posFunc = m_this.style.get('position'),
         tmp, diag;
     s_update.call(m_this);
 
@@ -67,8 +57,8 @@ var d3_pathFeature = function (arg) {
     data.forEach(function (d, i) {
       var src, trg;
       if (i < data.length - 1) {
-        src = d;
-        trg = data[i + 1];
+        src = posFunc(d, i);
+        trg = posFunc(data[i + 1], i + 1);
         tmp.push({
           source: m_this.featureGcsToDisplay(src),
           target: m_this.featureGcsToDisplay(trg)
@@ -84,8 +74,8 @@ var d3_pathFeature = function (arg) {
     m_style.append = 'path';
     m_style.classes = ['d3PathFeature'];
     m_style.style = $.extend({
-      'fill': function () { return false; },
-      'fillColor': function () { return { r: 0, g: 0, b: 0 }; }
+      fill: function () { return false; },
+      fillColor: {r: 0, g: 0, b: 0}
     }, s_style);
     m_style.visible = m_this.visible;
 
@@ -97,9 +87,9 @@ var d3_pathFeature = function (arg) {
   };
 
   /**
-   * Update
+   * Update.
    *
-   * @override
+   * @returns {this}
    */
   this._update = function () {
     s_update.call(m_this);
diff --git a/src/pathFeature.js b/src/pathFeature.js
index c007cbfc20..6e74954d11 100644
--- a/src/pathFeature.js
+++ b/src/pathFeature.js
@@ -3,11 +3,32 @@ var inherit = require('./inherit');
 var feature = require('./feature');
 
 /**
- * Create a new instance of class pathFeature
+ * Specification for pathFeature.
+ *
+ * @typedef {geo.feature.spec} geo.pathFeature.spec
+ * @extends {geo.feature.spec}
+ * @property {geo.geoPosition|function} [position] Position of the data.
+ *   Default is (data).
+ */
+
+/**
+ * Style specification for a path feature.
+ *
+ * @typedef {geo.feature.styleSpec} geo.pathFeature.styleSpec
+ * @extends geo.feature.styleSpec
+ * @property {geo.geoColor|function} [strokeColor='white'] Color to stroke each
+ *   path.
+ * @property {number|function} [strokeWidth=1] The weight of the path's
+ *   stroke in pixels.
+ */
+
+/**
+ * Create a new instance of class pathFeature.
  *
  * @class
  * @alias geo.pathFeature
  * @extends geo.feature
+ * @param {geo.pathFeature.spec} arg
  * @returns {geo.pathFeature}
  */
 var pathFeature = function (arg) {
@@ -18,33 +39,35 @@ var pathFeature = function (arg) {
   arg = arg || {};
   feature.call(this, arg);
 
-  /**
-   * @private
-   */
   var m_this = this,
-      m_position = arg.position === undefined ? [] : arg.position,
       s_init = this._init;
 
   this.featureType = 'path';
 
   /**
-   * Get/Set positions
+   * Get/Set position.
    *
-   * @returns {geo.pathFeature}
+   * @param {function|geo.geoPosition} [val] If not specified, return the
+   *    position accessor.  Otherwise, change the position accessor.
+   * @returns {this|function}
    */
   this.position = function (val) {
     if (val === undefined) {
-      return m_position;
+      return m_this.style('position');
+    }
+    if (val !== m_this.style('position')) {
+      m_this.style('position', val);
+      m_this.dataTime().modified();
+      m_this.modified();
     }
-    // Copy incoming array of positions
-    m_position = val;
-    m_this.dataTime().modified();
-    m_this.modified();
     return m_this;
   };
 
   /**
-   * Initialize
+   * Initialize.
+   *
+   * @param {geo.pathFeature.spec} arg The feature specification.
+   * @returns {this}
    */
   this._init = function (arg) {
     s_init.call(m_this, arg);
@@ -52,17 +75,22 @@ var pathFeature = function (arg) {
     var defaultStyle = $.extend(
       {},
       {
-        'strokeWidth': function () { return 1; },
-        'strokeColor': function () { return { r: 1.0, g: 1.0, b: 1.0 }; }
+        strokeWidth: 1,
+        strokeColor: {r: 1.0, g: 1.0, b: 1.0},
+        position: function (d) { return d; }
       },
       arg.style === undefined ? {} : arg.style
     );
 
+    if (arg.position !== undefined) {
+      defaultStyle.position = arg.position;
+    }
     m_this.style(defaultStyle);
-
-    if (m_position) {
-      m_this.dataTime().modified();
+    if (defaultStyle.position) {
+      m_this.position(defaultStyle.position);
     }
+    m_this.dataTime().modified();
+    return m_this;
   };
 
   this._init(arg);