Add documentation for selectors and plugins (#1798)

This is a porting of the documentation developed wrote durin the work on 3d.
* Search
* Zoom In
* ZoomOut 
* ScaleBox
* Locate
* CoordinateUtils.

docma-config.json

@@ -134,6 +134,7 @@
             "web/client/epics/search.js",
 
             "web/client/utils/index.jsdoc",
+            "web/client/utils/CoordinatesUtils.js",
             "web/client/utils/PluginsUtils.js",
             "web/client/utils/ShareUtils.js"
           ],
@@ -150,9 +151,13 @@
                 "web/client/plugins/MeasureResults.jsx",
                 "web/client/plugins/FullScreen.jsx",
                 "web/client/plugins/Identify.jsx",
+                "web/client/plugins/Locate.jsx",
                 "web/client/plugins/Login.jsx",
+                "web/client/plugins/ScaleBox.jsx",
                 "web/client/plugins/ScrollTop.jsx",
-                "web/client/plugins/Search.jsx"
+                "web/client/plugins/Search.jsx",
+                "web/client/plugins/ZoomIn.jsx",
+                "web/client/plugins/ZoomOut.jsx"
             ]
         },
         "./docs/**/*md",

web/client/epics/index.jsdoc

@@ -3,3 +3,8 @@
  * @see {@link https://redux-observable.js.org/docs/basics/Epics.html|the redux-observable documentation} for details
  * @name epics
  */
+ /**
+  * @external Observable
+  * @description A RxJS Observable
+  * @see {@link http://reactivex.io/rxjs/class/es6/Observable.js~Observable.html|Observable}
+  */

web/client/plugins/DrawerMenu.jsx

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright 2016, GeoSolutions Sas.
  * All rights reserved.
  *

web/client/plugins/Locate.jsx

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright 2016, GeoSolutions Sas.
  * All rights reserved.
  *
@@ -16,6 +16,19 @@ const {Glyphicon} = require('react-bootstrap');
 
 const assign = require('object-assign');
 
+/**
+  * Locate Plugin. Provides button to locate the user's position on the map.
+  * By deafault it will follow the user until he moves the map. He can click again to
+  * restore the following mode.
+  * @class  Locate
+  * @memberof plugins
+  * @static
+  *
+  * @prop {string} cfg.style CSS to apply to the button
+  * @prop {string} cfg.text The button text, if any
+  * @prop {string} cfg.className the class name for the button
+  *
+  */
 const LocatePlugin = connect((state) => ({
     locate: state.locate && state.locate.state || 'DISABLED'
 }), {

web/client/plugins/ScaleBox.jsx

@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright 2016, GeoSolutions Sas.
  * All rights reserved.
  *
@@ -30,6 +30,18 @@ const selector = createSelector([mapSelector], (map) => ({
 
 require('./scalebox/scalebox.css');
 
+/**
+  * ScaleBox Plugin. Provides a selector for the scale of the map.
+  * @class  ScaleBox
+  * @memberof plugins
+  * @static
+  *
+  * @prop {object} cfg.style CSS to apply to the scalebox
+  * @prop {Boolean} cfg.readOnly the selector is readonly
+  * @prop {string} cfg.label label for the selector
+  * @prop {Boolean} cfg.useRawInput set true if you want to use an normal html input object
+  *
+  */
 const ScaleBoxPlugin = React.createClass({
     render() {
         return (<HelpWrapper id="mapstore-scalebox-container"

web/client/plugins/ZoomIn.jsx

@@ -17,6 +17,16 @@ const {changeZoomLevel} = require('../actions/map');
 
 const Message = require('../components/I18N/Message');
 
+/**
+  * ZoomIn Plugin. Provides button to zoom in
+  * @class  ZoomIn
+  * @memberof plugins
+  * @static
+  *
+  * @prop {object} cfg.style CSS to apply to the button
+  * @prop {string} cfg.className the class name for the button
+  *
+  */
 const ZoomInButton = connect(selector, {
     onZoom: changeZoomLevel
 })(require('../components/buttons/ZoomButton'));

web/client/plugins/ZoomOut.jsx

@@ -1,13 +1,10 @@
-/**
+/*
  * Copyright 2016, GeoSolutions Sas.
  * All rights reserved.
  *
  * This source code is licensed under the BSD-style license found in the
  * LICENSE file in the root directory of this source tree.
  */
- /**
- * Plugin for Zoom out
- */
 const React = require('react');
 const {connect} = require('react-redux');
 const {createSelector} = require('reselect');
@@ -19,6 +16,16 @@ const {changeZoomLevel} = require('../actions/map');
 
 const Message = require('../components/I18N/Message');
 
+/**
+  * ZoomOut Plugin. Provides button to zoom out
+  * @class  ZoomOut
+  * @memberof plugins
+  * @static
+  *
+  * @prop {object} cfg.style CSS to apply to the button
+  * @prop {string} cfg.className the class name for the button
+  *
+  */
 const ZoomOutButton = connect(selector, {
     onZoom: changeZoomLevel
 })(require('../components/buttons/ZoomButton'));

web/client/selectors/index.jsdoc

@@ -0,0 +1,11 @@
+/**
+ * React/Redux selectors.
+ * @see {@link https://github.com/reactjs/reselect|Reselect} for details
+ * @name selectors
+ *
+ */
+/**
+ * @external selector
+ * @see {@link https://github.com/reactjs/reselect|Reselect} for details
+ * @description A function that computes the redux state or part of it allowing the redux store to be normalized and the react components to be re-rendered only if needed.
+ */

web/client/selectors/map.js

@@ -1,4 +1,4 @@
-/**
+/*
 * Copyright 2016, GeoSolutions Sas.
 * All rights reserved.
 *
@@ -10,11 +10,24 @@ const CoordinatesUtils = require('../utils/CoordinatesUtils');
 const MapUtils = require('../utils/MapUtils');
 const {createSelector} = require('reselect');
 
+/**
+ * get the current map configuration from state
+ * @function
+ * @memberof selectors.map
+ * @param  {object} state the state
+ * @return {object} the map configruation
+ */
 const mapSelector = (state) => (state.map && state.map.present) || (state.map) || (state.config && state.config.map) || null;
 
 const projectionSelector = createSelector([mapSelector], (map) => map && map.projection);
 
-
+/**
+ * Get the scales of the current map
+ * @function
+ * @memberof selectors.map
+ * @param  {object} state the state
+ * @return {number[]} the scales of the map
+ */
 const scalesSelector = createSelector(
     [projectionSelector],
     (projection) => {

web/client/utils/CoordinatesUtils.js

@@ -1,10 +1,11 @@
-/**
+/*
  * Copyright 2015, GeoSolutions Sas.
  * All rights reserved.
  *
  * This source code is licensed under the BSD-style license found in the
  * LICENSE file in the root directory of this source tree.
  */
+
 const Proj4js = require('proj4');
 const proj4 = Proj4js;
 const assign = require('object-assign');
@@ -48,7 +49,10 @@ function determineCrs(crs) {
     }
     return crs;
 }
-
+/**
+ * Utilities for Coordinates conversion.
+ * @memberof utils
+ */
 const CoordinatesUtils = {
     getUnits: function(projection) {
         const proj = new Proj4js.Proj(projection);
@@ -126,11 +130,9 @@ const CoordinatesUtils = {
     },
     /**
      * Reprojects a bounding box.
-     *
      * @param bbox {array} [minx, miny, maxx, maxy]
      * @param source {string} SRS of the given bbox
      * @param dest {string} SRS of the returned bbox
-     *
      * @return {array} [minx, miny, maxx, maxy]
      */
     reprojectBbox: function(bbox, source, dest, normalize = true) {

web/client/utils/PluginsUtils.js

@@ -155,7 +155,6 @@ const defaultEpicWrapper = epic => (...args) =>
   });
 /**
  * Utilities to manage plugins
- * @class
  * @memberof utils
  */
 const PluginsUtils = {

web/client/utils/ShareUtils.js

@@ -8,9 +8,8 @@
 const Url = require('url');
 
 /**
- * Utility functions for Share tools
+ * Utility functions for Share tools.
  * @memberof utils
- * @type {Object}
  */
 var ShareUtils = {
     /**