Documented plugin utils (#1621)

* documented plugin utils * fixed documentation for plugin utils * add jsdoc indexes and more documentation. Fixed pluginUtils jsdoc * fixed typo. Added missing export
geosolutions-it · Mar 22, 2017 · 1839f96 · 1839f96
1 parent 530d34f
commit 1839f96
Show file tree

Hide file tree

Showing 12 changed files with 102 additions and 15 deletions.
diff --git a/docma-config.json b/docma-config.json
@@ -62,10 +62,8 @@
                     "iconClass": "ico-mouse-pointer",
                     "label": "Reference",
                     "items": [
-                        { "label": "Components", "href": "api/components"},
-                        { "label": "Actions", "href": "api/actions" },
-                        { "label": "Reducers", "href": "api/reducers" },
-                        { "label": "Epics", "href": "api/epics" },
+                        { "label": "Framework", "href": "api/framework"},
+
                         { "separator": true },
                         { "label": "Plugins", "href": "api/plugins" }
 
@@ -106,11 +104,24 @@
     },
     "src": [
         {
-          "components" : ["web/client/components/mapcontrols/search/SearchBar.jsx"],
-           "actions" : ["web/client/actions/search.js"],
-           "reducers" : ["web/client/reducers/search.js"],
-            "epics": "web/client/epics/search.js",
+          "framework" : [
+            "web/client/components/index.jsdoc",
+            "web/client/components/mapcontrols/search/SearchBar.jsx",
+
+            "web/client/actions/index.jsdoc",
+            "web/client/actions/search.js",
+
+            "web/client/reducers/index.jsdoc",
+            "web/client/reducers/search.js",
+
+            "web/client/epics/index.jsdoc",
+            "web/client/epics/search.js",
+
+            "web/client/utils/index.jsdoc",
+            "web/client/utils/PluginsUtils.js"
+          ],
             "plugins": [
+                "web/client/plugins/index.jsdoc",
                 "web/client/plugins/Search.jsx",
                 "web/client/plugins/BackgroundSwitcher.jsx",
                 "web/client/plugins/Map.jsx",

diff --git a/inch.json b/inch.json
@@ -4,6 +4,7 @@
       "web/client/plugins/*.jsx",
       "web/client/actions/*js",
       "web/client/reducers/*js",
+      "web/client/utils/*.js",
       "web/client/epics/*js",
       "web/client/jsapi/*js"
     ]

diff --git a/web/client/actions/config.js b/web/client/actions/config.js
@@ -93,4 +93,4 @@ function loadMapInfo(url, mapId) {
 }
 module.exports = {MAP_CONFIG_LOADED, MAP_CONFIG_LOAD_ERROR,
     MAP_INFO_LOAD_START, MAP_INFO_LOADED, MAP_INFO_LOAD_ERROR,
-     loadMapConfig, loadMapInfo, configureMap};
+     loadMapConfig, loadMapInfo, configureMap, configureError};
diff --git a/web/client/actions/index.jsdoc b/web/client/actions/index.jsdoc
@@ -0,0 +1,6 @@
+/**
+ * Redux actions.
+ * @see {@link http://redux.js.org/docs/basics/Actions.html|the redux documentation} for details
+ * @name actions
+ *
+ */
diff --git a/web/client/actions/search.js b/web/client/actions/search.js
@@ -5,7 +5,6 @@
  * This source code is licensed under the BSD-style license found in the
  * LICENSE file in the root directory of this source tree.
  */
-
 const TEXT_SEARCH_STARTED = 'TEXT_SEARCH_STARTED';
 const TEXT_SEARCH_RESULTS_LOADED = 'TEXT_SEARCH_RESULTS_LOADED';
 const TEXT_SEARCH_PERFORMED = 'TEXT_SEARCH_PERFORMED';
@@ -158,6 +157,10 @@ function cancelSelectedItem(item) {
     };
 }
 
+/**
+ * Actions for search
+ * @name actions.search
+ */
 module.exports = {
     TEXT_SEARCH_STARTED,
     TEXT_SEARCH_LOADING,

diff --git a/web/client/components/index.jsdoc b/web/client/components/index.jsdoc
@@ -0,0 +1,6 @@
+/**
+ * React components
+ * @see {@link https://facebook.github.io/react/docs/react-component.html|the React documentation} for details
+ * @name components
+ *
+ */
diff --git a/web/client/epics/index.jsdoc b/web/client/epics/index.jsdoc
@@ -0,0 +1,5 @@
+/**
+ * redux-observable epics
+ * @see {@link https://redux-observable.js.org/docs/basics/Epics.html|the redux-observable documentation} for details
+ * @name epics
+ */
diff --git a/web/client/epics/search.js b/web/client/epics/search.js
@@ -35,9 +35,9 @@ const {get} = require('lodash');
  * Gets every `TEXT_SEARCH_STARTED` event.
  * Dispatches the request to all the services in the action, postprocess them
  * and updates every tume the results
- * @param {Observable} action$ manages `TEXT_SEARCH_STARTED` and `TEXT_SEARCH_RESULTS_PURGE`, `TEXT_SEARCH_RESET`, `TEXT_SEARCH_ITEM_SELECTED` for cancellation
+ * @param {external:Observable} action$ manages `TEXT_SEARCH_STARTED` and `TEXT_SEARCH_RESULTS_PURGE`, `TEXT_SEARCH_RESET`, `TEXT_SEARCH_ITEM_SELECTED` for cancellation
  * @memberof epics.search
- * @return {Observable}
+ * @return {external:Observable}
  */
 const searchEpic = action$ =>
   action$.ofType(TEXT_SEARCH_STARTED)
@@ -130,7 +130,10 @@ const searchItemSelected = action$ =>
         }
         return Rx.Observable.from(actions);
     });
-
+    /**
+     * Actions for search
+     * @name epics.search
+     */
 module.exports = {
     searchEpic,
     searchItemSelected

diff --git a/web/client/plugins/index.jsdoc b/web/client/plugins/index.jsdoc
@@ -0,0 +1,6 @@
+/**
+ * MapStore2 plugins
+ * @name plugins
+ * @see {@link plugins-architecture}
+ *
+ */
diff --git a/web/client/reducers/index.jsdoc b/web/client/reducers/index.jsdoc
@@ -0,0 +1,6 @@
+/**
+ * Redux reducers.
+ * @see {@link http://redux.js.org/docs/basics/Reducers.html|the redux documentation} for details
+ * @name reducers
+ *
+ */
diff --git a/web/client/utils/PluginsUtils.js b/web/client/utils/PluginsUtils.js
@@ -1,4 +1,4 @@
-/**
+/*
  * Copyright 2016, GeoSolutions Sas.
  * All rights reserved.
  *
@@ -121,17 +121,29 @@ const getReducers = (plugins) => Object.keys(plugins).map((name) => plugins[name
                             .reduce((previous, current) => assign({}, previous, current), {});
 const getEpics = (plugins) => Object.keys(plugins).map((name) => plugins[name].epics)
                             .reduce((previous, current) => assign({}, previous, current), {});
+
+/**
+ * Utilities to manage plugins
+ * @class
+ * @memberof utils
+ */
 const PluginsUtils = {
     /**
      * Produces the reducers from the plugins, combined with other plugins
      * @param {array} plugins the plugins
-     * @param {array} reducers other plugins
+     * @param {object} [reducers] other reducers
      * @returns {function} a reducer made from the plugins' reducers and the reducers passed as 2nd parameter
      */
     combineReducers: (plugins, reducers) => {
         const pluginsReducers = getReducers(plugins);
         return combineReducers(assign({}, reducers, pluginsReducers));
     },
+    /**
+     * Produces the rootEpic for the plugins, combined with other epics passed as 2nd argument
+     * @param {array} plugins the plugins
+     * @param {function[]} [epics] the epics to add to the plugins' ones
+     * @return {function} the rootEpic, obtained combining plugins' epics and the other epics passed as argument.
+     */
     combineEpics: (plugins, epics = []) => {
         const pluginEpics = getEpics(plugins);
         return combineEpics(...[ ...Object.keys(pluginEpics).map(k => pluginEpics[k]), ...epics]);
@@ -140,6 +152,29 @@ const PluginsUtils = {
     filterState,
     getPlugins: (plugins) => Object.keys(plugins).map((name) => plugins[name])
                                 .reduce((previous, current) => assign({}, previous, omit(current, 'reducers')), {}),
+    /**
+     * provide the pluginDescriptor for a given plugin, with a state and a configuration
+     * @param {object} state the state. This is required to laod plugins that depend from the state itself
+     * @param {object} plugins all the plugins, like this:
+     * ```
+     *  {
+     *      P1Plugin: connectdComponent1,
+     *      P2Plugin: connectdComponent2
+     *  }
+     * ```
+     * @param {array} pluginConfig the configurations of the plugins
+     * @param {object} [loadedPlugins] the plugins loaded with `require.ensure`
+     * @return {object} a pluginDescriptor like this:
+     * ```
+     * {
+     *    id: "P1",
+     *    name: "P1",
+     *    items: // the contained items
+     *    cfg: // the configuration
+     *    impl // the real implementation
+     * }
+     * ```
+     */
     getPluginDescriptor: (state, plugins, pluginsConfig, pluginDef, loadedPlugins = {}) => {
         const name = isObject(pluginDef) ? pluginDef.name : pluginDef;
         const id = isObject(pluginDef) ? pluginDef.id : null;

diff --git a/web/client/utils/index.jsdoc b/web/client/utils/index.jsdoc
@@ -0,0 +1,5 @@
+/**
+ * Misc utility objects and methods
+ * @name utils
+ *
+ */