DM-7038: added proper tags in few files to generate javascript docs; created configuration file, jsdoc_config.json and added depency libraries to the package.json

Author: Lijun Zhang

jsdoc_config.json

@@ -0,0 +1,79 @@
+{
+    "tags": {
+        "allowUnknownTags| ": true,
+        "dictionaries": ["jsdoc","closure"]
+    },
+    "source": {
+        "include": [
+           "src/firefly/js/api/",
+           "src/firefly/js/tables/TableUtil.js",
+           "src/firefly/js/charts/XYPlotCntlr.js",
+           "src/firefly/js//visualize/CsysConverter.js",
+           "src/firefly/js/visualize/DrawLayerCntlr.js"
+          // ,"src/firefly/js/charts/HistogramCntlr.js"
+            ,"README.md"
+
+        ],
+      "exclude": [
+          //"src/firefly/js/api/ApiBuild.js"
+       ],
+        //include .js, .jsdoc and jsx files
+        "includePattern": ".+\\.js(doc)?|(x)$",
+         //Any file starting with an underscore or in a directory starting with an underscore will be ignored
+        "excludePattern": "(^|\\/|\\\\)_"
+    },
+
+    "plugins": [
+       "plugins/markdown",
+       "plugins/summarize"
+    ],
+
+   "markdown" : {
+    "idInHeadings" : true
+   },
+
+  "jsx": {
+        "extensions": ["js", "jsx"]
+    },
+   "staticFiles": {
+        "include": ["./docs"],
+        "exclude": ["./docs/firefly-api-code-examples.md"],
+        "includePattern": ".+\\.md?$",
+       // "excludePattern": "(^|\\/|\\\\)_",
+        "recursive": true//,
+        //"recursiveLevel": 2,
+    },
+
+    "templates": {
+          "minami": {
+         // "default": {
+            "staticFiles": {
+                "include": ["./docs/"],
+                "exclude": ["./docs/firefly-api-code-examples.md"],
+               // "includePattern": ".+\\.md?$",
+                // "excludePattern": "(^|\\/|\\\\)_",
+                "recursive": true//,
+                //"recursiveLevel": 2,
+            }
+
+        }
+    },
+    "opts": {
+        "template": "node_modules/minami", //use the minami template insetad of the default
+       // "template":  "templates/default",//default",  // same as -t templates/default
+       "encoding": "utf8",               // same as -e utf8
+        "destination": "./jsdoc/",          // same as -d ./out/
+        "recurse": true , //,             // same as -r
+        "tutorials": "./tutorial/",// same as -u path/to/tutorials
+        "access": "all"   //same as -a  <value>, values are all, public, private etc
+
+    },
+    "templates": {
+        "cleverLinks": false,
+        "monospaceLinks": false,
+        "default": {
+            "outputSourceFiles": false
+        }
+    }
+}
+

package.json

@@ -84,7 +84,8 @@
     "style-loader": "^0.12.3",
     "url-loader": "^0.5.7",
     "webpack": "^1.8.2",
-    "react-addons-perf" : "0.14.7"
-
+    "eslint-plugin-jsx-a11y": "^0.6.2",
+    "jsdoc-jsx": "^0.1.0",
+    "minami": "^1.1.1"
   }
 }

src/firefly/js/api/ApiBuild.js

@@ -51,10 +51,12 @@ import './ApiStyle.css';
 
 /**
  * Start in api mode. Will create the api and call window.onFireflyLoaded(firefly)
+ * @ignore
  */
 export function initApi() {
     const lowlevelApi= buildLowlevelAPI();
     const viewInterface= buildViewerApi();
+
     const highLevelApi= buildHighLevelApi(lowlevelApi);
     if (!window.firefly) window.firefly= {};
     window.firefly.ignoreHistory = true;
@@ -69,7 +71,8 @@ export function initApi() {
 
 
 /**
-Structure of API
+
+  Structure of API
    {
               //--- High level API , all high level api are in the root
      all high level functions....
@@ -92,9 +95,8 @@ Structure of API
 
 /**
  * Return the api object.
- * 
  * @return {{action:{},ui:{},util:{}}}
- *
+ * @ignore
  */
 export function buildLowlevelAPI() {
 
@@ -142,7 +144,7 @@ export function buildLowlevelAPI() {
         PopupMouseReadoutMinimal,
         PopupMouseReadoutFull
     };
-    
+
     const util= Object.assign({}, ApiUtil, {image:ApiUtilImage}, {chart:ApiUtilChart}, {table:ApiUtilTable}, {data:{}} );
 
     return { action, ui, util };
@@ -153,6 +155,7 @@ export function buildLowlevelAPI() {
  * pull all the dispatch functions out of the object
  * @param obj
  * @return {*}
+ * @ignore
  */
 function findDispatch(obj) {
    return Object.keys(obj).reduce( (res,key) => {
@@ -167,6 +170,7 @@ function findDispatch(obj) {
  * @param obj
  * @param prefix
  * @return {*}
+ * @ignore
  */
 function findActionType(obj,prefix) {
     return Object.keys(obj).reduce( (res,key) => {

src/firefly/js/api/ApiHighlevelBuild.js

@@ -14,9 +14,16 @@
 //===================================================================================
 
 /**
- * 
+ * @public
+ * @desc build highLevelApi using the lowLevelApi as an input
+ * @module firefly
+ */
+
+/**
  * @param llApi the lowlevel api
  * @return {Object}
+ * @ignore
+ *
  */
 export function buildHighLevelApi(llApi) {
     const current= build(llApi);
@@ -32,6 +39,7 @@ var globalImageViewDefParams= {};
  * Build the deprecated API
  * @param llApi
  * @return {Object}
+ * @ignore
  */
 function build(llApi) {
 
@@ -111,7 +119,9 @@ function buildTablePart(llApi) {
     const {dispatchTableFetch}= llApi.action;
 
     /**
-     * @typedef {object} TblOptions    table options
+     * @global
+     * @public
+     * @typedef {object} TblOptions
      * @prop {string}  tbl_group    the group this table belongs to.  Defaults to 'main'.
      * @prop {boolean} removable    true if this table can be removed from view.  Defaults to true.
      * @prop {boolean} showUnits    defaults to false
@@ -123,11 +133,14 @@ function buildTablePart(llApi) {
      */
 
     /**
-     * The general plotting function to plot a table.
      * @param {string|HTMLDivElement} targetDiv to put the table in.
      * @param {Object} request         request object created from
      * @param {TblOptions} options     table options.
+     * @memberof module:firefly
+     * @public
+     * @example fierfly.showTable
      */
+    // @param {module:firefly.TblOptions} options     table options.
     const showTable= (targetDiv, request, options)  => doShowTable(llApi, targetDiv, request, options);
 
     return {showTable};
@@ -139,7 +152,9 @@ function buildTablePart(llApi) {
 function buildChartPart(llApi) {
 
     /**
-     * @typedef {object} XYPlotOptions  xy plot options
+     * @global
+     * @public
+     * @typedef {object} XYPlotOptions
      * @prop {string}  source       location of the ipac table, url or file path; ignored when XY plot view is added to table
      * @prop {string}  QUERY_ID     required when XY plot view is added to the table. It connects this XY Plot to the table and should be the same string that you specified as the div parameter when you created the table.
      * @prop {string}  chartTitle   title of the chart
@@ -155,30 +170,36 @@ function buildChartPart(llApi) {
      * @prop {string}  yOptions     comma separated list of y axis options: grid,flip,log
      */
 
+
     /**
-     * The general plotting function to plot an XY Plot.
+     * @summary The general plotting function to plot an XY Plot.
      * @param {string|HTMLDivElement} targetDiv to put the chart in.
      * @param {XYPlotOptions} parameters the request object literal with the chart parameters
-     * @namespace firefly
+     * @memberof module:firefly
+     * @example firefly.showXYPlot
+     * @public
      */
     const showXYPlot= (targetDiv, parameters)  => doShowXYPlot(llApi, targetDiv, parameters);
-
     /**
-     * Add XY Plot view of an existing table.
+     * @summary  It appears twice when it is added in the above jsdoc block
      * @param {string|HTMLDivElement} targetDiv to put the chart in.
-     * @param {XYPlotOptions} parameters the request object literal with the chart parameters
-     * @namespace firefly
+     * @param {module:firefly.XYPlotOptions} parameters the request object literal with the chart parameters
+     * @memberof module:firefly
+     * @public
+     * @example firefly.addXYPlot
      */
+
     const addXYPlot= (targetDiv, parameters) => doShowXYPlot(llApi, targetDiv, parameters);
 
     return {showXYPlot, addXYPlot};
 }
 
 function buildCommon(llApi) {
     /**
-     * Sets the root path for any relative URL. If this method has not been called then relative URLs use the page's root.
+     * @summary Sets the root path for any relative URL. If this method has not been called then relative URLs use the page's root.
      * @param {String} rootUrlPath
-     * @namespace firefly
+     * @memberof module:firefly
+     * @public
      */
     const setRootPath= (rootUrlPath) => llApi.action.dispatchRootUrlPath(rootUrlPath);
 
@@ -187,41 +208,60 @@ function buildCommon(llApi) {
 
 function buildImagePart(llApi) {
 
+
     const {RequestType}= llApi.util.image;
 
-    /**
-     * The general plotting function to plot a FITS image.
-     * @param {String|div} targetDiv to put the image in.
-     * @param {Object} request the request object literal with the plotting parameters
-     * @namespace firefly
+     /**
+      * @summary The general plotting function to plot a FITS image.
+      * @param {String|div} targetDiv to put the image in.
+      * @param {Object} request the request object literal with the plotting parameters
+      * @memberof module:firefly
+      * @public
+      * @ignore
+      * @example firefly.showImage
+      *
      */
     const showImage= (targetDiv, request)  => showImageInMultiViewer(llApi, targetDiv, request);
 
-
     /**
-     * a convenience plotting function to plot a file on the server or a url.  If first looks for the file then
+     * @summary a convenience plotting function to plot a file on the server or a url.  If first looks for the file then
      * the url is the fallback
      * @param {String|div} targetDiv to put the image in.
      * @param {String} file file on server
      * @param {String} url url reference to a fits file
-     * @namespace firefly
+     * @memberof module:firefly
+     * @public
+     * @ignore
+     * @example firefly.showImageFileOrUrl
      */
+
     const showImageFileOrUrl= (targetDiv, file,url) =>
               showImageInMultiViewer(llApi, targetDiv,
                                            {'File' : file,
                                             'URL' : url,
                                             'Type' : RequestType.TRY_FILE_THEN_URL
                                            });
 
+
     /**
-     * set global fallback params for every image plotting call
+     * @summary set global fallback params for every image plotting call
      * @param {Object} params a object literal such as any image plot or showImage uses
-     * @namespace firefly
+     * @memberof module:firefly
+     * @public
+     * @ignore
+     * @example firefly.setGlobalImageDef
      */
     const setGlobalImageDef= (params) => globalImageViewDefParams= params;
 
 
-
+    /**
+     *
+     * @param {div} targetDiv to put the coverage in.
+     * @param options  an object literal containing a list of the coverage options
+     * @memberof module:firefly
+     * @public
+     * @example firefly.showCoverage
+     */
     const showCoverage= (div,options) => initCoverage(llApi,div,options);
 
     return {showImage, showImageFileOrUrl, setGlobalImageDef, showCoverage};
@@ -232,6 +272,7 @@ function buildImagePart(llApi) {
  * @param llApi
  * @return {Object}
  * @Deprecated
+ * @ignore
  */
 function buildDeprecated(llApi) {