Merge pull request #951 from OpenGeoscience/slider-widget-jsdocs

Fix jsdocs for the sliderWidget.

src/ui/legendWidget.js

@@ -3,11 +3,38 @@ var inherit = require('../inherit');
 var registerWidget = require('../registry').registerWidget;
 
 /**
- * Create a new instance of class legendWidget
+ * @typedef {object} geo.gui.legendWidget.categorySpec
+ *
+ * @property {string} name The name of the category.
+ * @property {string} type The type of the category.  `point` shows as a
+ *   circle, `line` as a line segment, all others as a rounded rectangle.
+ * @property {geo.gui.legendWidget.styleSpec} style The style for the category.
+ */
+
+/**
+ * Style specification for a legend category.
+ *
+ * @typedef {geo.feature.styleSpec} geo.gui.legendWidget.styleSpec
+ * @extends geo.feature.styleSpec
+ * @property {boolean|function} [stroke=true] True to stroke legend.
+ * @property {geo.geoColor|function} [strokeColor] Color to stroke each legend.
+ * @property {number|function} [strokeOpacity=1] Opacity for each legend's
+ *   stroke.  Opacity is on a [0-1] scale.
+ * @property {number|function} [strokeWidth=1.5] The weight of the legend's
+ *   stroke in pixels.
+ * @property {boolean|function} [fill=true] True to fill legend.
+ * @property {geo.geoColor|function} [fillColor] Color to fill each legend.
+ * @property {number|function} [fillOpacity=1] Opacity for each legend.
+ *   Opacity is on a [0-1] scale.
+ */
+
+/**
+ * Create a new instance of class geo.gui.legendWidget.
  *
  * @class
  * @alias geo.gui.legendWidget
  * @extends geo.gui.svgWidget
+ * @param {geo.gui.widget.spec} arg Options for the widget.
  * @returns {geo.gui.legendWidget}
  */
 var legendWidget = function (arg) {
@@ -20,7 +47,6 @@ var legendWidget = function (arg) {
   var d3 = require('../d3/d3Renderer').d3;
   var geo_event = require('../event');
 
-  /** @private */
   var m_this = this,
       m_categories = [],
       m_top = null,
@@ -30,29 +56,12 @@ var legendWidget = function (arg) {
       m_padding = 12; // padding in pixels inside the border
 
   /**
-   * Get or set the category array associated with
-   * the legend.  Each element of this array is
-   * an object: ::
-   *     {
-   *         name: string,
-   *         style: object,
-   *         type: 'point' | 'line' | ...
-   *     }
-   *
-   * The style property can contain the following feature styles:
-   *     * fill: bool
-   *     * fillColor: object | string
-   *     * fillOpacity: number
-   *     * stroke: bool
-   *     * strokeColor: object | string
-   *     * strokeWidth: number
-   *     * strokeOpacity: number
+   * Get or set the category array associated with the legend.
    *
-   * The type controls how the element is displayed, point as a circle,
-   * line as a line segment.  Any other value will display as a rounded
-   * rectangle.
-   *
-   * @param {object[]?} categories The categories to display
+   * @param {geo.gui.legendWidget.categorySpec[]} [arg] The categories to
+   *   display.
+   * @returns {geo.gui.legendWidget.categorySpec[]|this} The current categories
+   *   or the widget instance.
    */
   this.categories = function (arg) {
     if (arg === undefined) {
@@ -70,8 +79,9 @@ var legendWidget = function (arg) {
   };
 
   /**
-   * Get the widget's size
-   * @returns {{width: number, height: number}} The size in pixels
+   * Return the size of the widget.
+   *
+   * @returns {geo.screenSize}
    */
   this.size = function () {
     var width = 1, height;
@@ -92,7 +102,9 @@ var legendWidget = function (arg) {
   };
 
   /**
-   * Redraw the legend
+   * Redraw the legend.
+   *
+   * @returns {this}
    */
   this.draw = function () {
 
@@ -189,7 +201,8 @@ var legendWidget = function (arg) {
 
   /**
    * Get scales for the x and y axis for the current size.
-   * @private
+   *
+   * @returns {object} An object with `x` and `y`, each containing a d3 scale.
    */
   this._scale = function () {
     return {

src/ui/sliderWidget.js

@@ -3,11 +3,20 @@ var inherit = require('../inherit');
 var registerWidget = require('../registry').registerWidget;
 
 /**
- * Create a new instance of class sliderWidget
+ * @typedef {geo.gui.widget.spec} geo.gui.sliderWidget.spec
+ * @extends {geo.gui.widget.spec}
+ * @property {number} [width=20] The width of the slider in pixels.
+ * @property {number} [height=160] The height of the slider in pixels.  The
+ *   actual bar is `height - 3 * width`.
+ */
+
+/**
+ * Create a new instance of class sliderWidget.
  *
  * @class
  * @alias geo.gui.sliderWidget
- * @extends {geo.gui.svgWidget}
+ * @extends geo.gui.svgWidget
+ * @param {geo.gui.sliderWidget.spec} arg Options for the widget.
  * @returns {geo.gui.sliderWidget}
  */
 var sliderWidget = function (arg) {
@@ -50,14 +59,12 @@ var sliderWidget = function (arg) {
   /**
    * Add an icon from a path string.  Returns a d3 group element.
    *
-   * @function
-   * @argument {string} icon svg path string
-   * @argument {Array} base where to append the element (d3 selection)
-   * @argument {number} cx Center x-coordinate
-   * @argument {number} cy Center y-coordinate
-   * @argument {number} size Icon size in pixels
-   * @returns {object}
-   * @private
+   * @param {string} icon svg path string.
+   * @param {d3Selection} base where to append the element.
+   * @param {number} cx Center x-coordinate.
+   * @param {number} cy Center y-coordinate.
+   * @param {number} size Icon size in pixels.
+   * @returns {d3GroupElement}
    */
   function put_icon(icon, base, cx, cy, size) {
     var g = base.append('g');
@@ -78,16 +85,19 @@ var sliderWidget = function (arg) {
     return g;
   }
 
+  /**
+   * Return the size of the widget.
+   *
+   * @returns {geo.screenSize}
+   */
   this.size = function () {
     return {width: m_width, height: m_height};
   };
 
   /**
-   * Initialize the slider widget in the map.
+   * Initialize the slider widget.
    *
-   * @function
-   * @returns {geo.gui.sliderWidget}
-   * @private
+   * @returns {this}
    */
   this._init = function () {
     m_this._createCanvas();
@@ -189,7 +199,12 @@ var sliderWidget = function (arg) {
         stroke: null
       });
 
-    // Respond to a mouse event on the widget
+    /**
+     * Respond to a mouse event on the widget.
+     *
+     * @param {d3Event} evt The event on the widget.
+     * @param {boolean} trans Truthy for an animated transition.
+     */
     function respond(evt, trans) {
       var z = m_yscale.invert(d3.mouse(svg.node())[1]),
           zrange = map.zoomRange();
@@ -255,7 +270,10 @@ var sliderWidget = function (arg) {
         d3.event.stopPropagation();
       });
 
-    var mouseOver = function () {
+    /**
+     * When the mouse is over the widget, change the style.
+     */
+    function mouseOver() {
       d3.select(this).attr('filter', 'url(#geo-highlight)');
       m_group.selectAll('rect,path,circle').transition()
         .duration(m_highlightDur)
@@ -265,10 +283,12 @@ var sliderWidget = function (arg) {
         .style('stroke', function (d) {
           return d.stroke || null;
         });
+    }
 
-    };
-
-    var mouseOut = function () {
+    /**
+     * When the mouse is no longer over the widget, change the style.
+     */
+    function mouseOut() {
       d3.select(this).attr('filter', null);
       m_group.selectAll('circle,rect,path').transition()
         .duration(m_highlightDur)
@@ -278,7 +298,7 @@ var sliderWidget = function (arg) {
         .style('stroke', function (d) {
           return m_lowContrast[d.stroke] || null;
         });
-    };
+    }
 
     m_group.selectAll('*')
       .on('mouseover', mouseOver)
@@ -289,14 +309,11 @@ var sliderWidget = function (arg) {
 
     mouseOut();
     m_this._update();
+    return m_this;
   };
 
   /**
    * Removes the slider element from the map and unbinds all handlers.
-   *
-   * @function
-   * @returns {geo.gui.sliderWidget}
-   * @private
    */
   this._exit = function () {
     m_this.geoOff(geo_event.zoom, m_this._update);
@@ -308,9 +325,8 @@ var sliderWidget = function (arg) {
    * Update the slider widget state in reponse to map changes.  I.e. zoom
    * range changes.
    *
-   * @function
-   * @returns {geo.gui.sliderWidget}
-   * @private
+   * @param {object} [obj] An object that can specify a zoom value.
+   * @param {number} [obj.zoom] The new zoom value to show on the slider.
    */
   this._update = function (obj) {
     var map = m_this.layer().map(),

src/ui/svgWidget.js

@@ -16,8 +16,7 @@ var registerWidget = require('../registry').registerWidget;
  * @class
  * @alias geo.gui.svgWidget
  * @extends geo.gui.widget
- * @param {object} arg
- * @param {geo.widget} [parent] A parent widget for this widget.
+ * @param {geo.gui.widget.spec} arg Options for the widget.
  * @returns {geo.gui.svgWidget}
  */
 var svgWidget = function (arg) {

src/ui/widget.js

@@ -16,16 +16,21 @@ var $ = require('jquery');
  *   allowed.  See the css specification for details.
  */
 
+/**
+ * @typedef {object} geo.gui.widget.spec
+ *
+ * @property {geo.layer} [layer] Layer associated with the widget.
+ * @property {geo.gui.widget.position} [position] Location of the widget.
+ * @property {geo.gui.widget} [parent] Optional parent widget.
+ */
+
 /**
  * Create a new instance of class widget.
  *
  * @class
  * @alias geo.gui.widget
- * @param {object} [arg] Options for the widget.
- * @param {geo.layer} [arg.layer] Layer associated with the widget.
- * @param {geo.gui.widget.position} [arg.position] Location of the widget.
- * @param {geo.gui.widget} [arg.parent] Optional parent widget.
  * @extends {geo.sceneObject}
+ * @param {geo.gui.widget.spec} [arg] Options for the widget.
  * @returns {geo.gui.widget}
  */
 var widget = function (arg) {