Update api docs

Author: knolleary

README.md

@@ -66,8 +66,6 @@ flow.walk(function(obj) {
 
 ```
 
-**TODO:** Add a better way to distinguish the object types
-
 ### Example - `export`
 
 The `export` function gives back the JSON array for the flow.

jsdoc.json

@@ -1,3 +1,6 @@
 {
-    "plugins":["jsdoc/include-parent.js"]
+    "plugins": [
+        "jsdoc/include-parent.js",
+        "plugins/markdown"
+    ]
 }

jsdoc/include-parent.js

@@ -1,19 +1,31 @@
 
+const doclets = {};
 const propertyMap = {};
 
 exports.handlers = {
     newDoclet: function(e) {
         if (e.doclet.kind === "class" && e.doclet.properties) {
-            propertyMap[e.doclet.name] = e.doclet.properties;
+            doclets[e.doclet.name] = e.doclet;
+            e.doclet.properties = e.doclet.properties || [];
         }
     },
     parseComplete: function(e) {
         e.doclets.forEach(doclet => {
-            if (doclet.augments) {
-                doclet.properties = doclet.properties || [];
-                doclet.properties = propertyMap[doclet.augments[0]].concat(doclet.properties)
+            if (doclet.kind === 'class' && doclet.augments) {
+                augmentWithParent(doclet,doclets[doclet.augments[0]]);
             }
         })
     }
 
 };
+
+function augmentWithParent(doclet,parentDoclet) {
+    doclet.properties = Array.from(new Set([...parentDoclet.properties, ...doclet.properties]))
+
+    if (!parentDoclet.augments || parentDoclet.augments.length === 0) {
+        return;
+    } else {
+        augmentWithParent(doclet,doclets[parentDoclet.augments[0]])
+    }
+
+}

lib/NRContainer.js

@@ -2,7 +2,7 @@ const NRObject = require("./NRObject.js");
 
 /**
  * NRContainer - Description
- * @property {object} nodes - Flow nodes in this flow/subflow/group
+ * @property {Set<NRNode>} nodes - Flow nodes in this flow/subflow/group
  */
 class NRContainer extends NRObject {
     /**

lib/NRFlow.js

@@ -3,9 +3,10 @@ const Symbols = require("./Symbols");
 
 /**
  * NRFlow - Description
- * @property {Set} configs - Configuration nodes in this flow/subflow
- * @property {Set} subflows - Subflows in this flow/subflow
- * @property {Set} groups - Groups in this flow/subflow
+ * @property {Set<NRConfigNode>} configs - Configuration nodes in this flow/subflow
+ * @property {Set<NRSubflow>} subflows - Subflows in this flow/subflow
+ * @property {Set<NRGroups>} groups - Groups in this flow/subflow
+ * @property {String} info - any documentation for this flow
  * @extends NRContainer
  */
 class NRFlow extends NRContainer {

lib/NRFlowSet.js

@@ -148,6 +148,12 @@ class NRFlowSet {
         addToParent(this.subflows);
     }
 
+
+    /**
+     * Export the flow as a Node Array that can be saves as JSON and loaded by Node-RED
+     *
+     * @return {Array} an array of node-red objects
+     */
     export() {
         let result = this.globals.exportContents();
         this.flows.forEach(n => {
@@ -158,6 +164,25 @@ class NRFlowSet {
         return result;
     }
 
+
+    /**
+     * Call the provided callback function for every object in the flow.
+     * The objects are recursively visited in the following order:
+     *
+     *  - Subflow definitions
+     *    - Config nodes scoped to this subflow
+     *    - Groups
+     *    - Nodes
+     *  - Global Config nodes
+     *  - Flows
+     *    - Config nodes scoped to this flow
+     *    - Groups
+     *    - Nodes
+     *
+     * @param {Function} callback - A function to call for every object in the flow.
+     *                              The function will receive the object as its
+     *                              first argument
+     */
     walk(callback) {
         this.globals.walk(callback);
         this.flows.forEach(n => n.walk(callback));

lib/NRGroup.js

@@ -3,7 +3,10 @@ const Symbols = require("./Symbols");
 
 /**
  * NRGroup - Description
- * @property {string} group - parent group, if set
+ * @property {String} groupId - if set, the id of the parent group this group is in (from `node.g`)
+ * @property {NRGroup} group - the parent group
+ * @property {String} info - any documentation for this group
+ * @property {object} style - style properties for this group
  * @extends NRContainer
  */
 class NRGroup extends NRContainer {

lib/NRNode.js

@@ -5,11 +5,17 @@ const Symbols = require("./Symbols");
  * NRNode - Description
  * @property {number} x - X location
  * @property {number} y - Y location
- * @property {number} groupId - if set, the id of the group this node is in
+ * @property {String} groupId - if set, the id of the group this node is in (from `node.g`)
+ * @property {NRGroup} group - group this node is part of, if set
  * @property {number} w - width (if known)
  * @property {number} h - height (if known)
- * @property {boolean} showLabel - whether the node displays its label
- * @property {string} group - group this node is part of, if set
+ * @property {boolean} showLabel - whether the node displays its label (from `node.l`)
+ * @property {String[][]} wires - the original `node.wires` property.
+ * @property {number} outputCount - the number of outputs the node has (from `node.wires.length`)
+ * @property {String} info - any documentation for this node
+ * @property {String} icon - a custom icon for the node, if set
+ * @property {String[]} inputLabels - array of custom labels for the node inputs
+ * @property {String[]} outputLabels - array of custom labels for the node outputs
  * @property {NRWire[]} inboundWires - Array of wires connected to an input of this node
  * @property {NRWire[]} outboundWires - Array of wires connected to an output of this node
  * @extends NRObject

lib/NRObject.js

@@ -5,7 +5,7 @@
  * @property {string} type - the type of the object
  * @property {boolean} disabled - whether the object is disabled
  * @property {object} config - the item-specific configuration properties
- * @property {NRFlow|NRSubflow} parent - the parent object. This will be the NRFlow/NRSubflow that 'owns' this object
+ * @property {NRFlow|NRSubflow} parent - the parent object. This will be the NRFlow/NRSubflow that 'owns' this object. As identified by `node.z`
  */
 class NRObject {
     /**
@@ -65,7 +65,7 @@ class NRObject {
             callback(this);
         }
     }
-    
+
     walkContents(callback) {
 
     }

lib/NRSubflow.js

@@ -3,7 +3,15 @@ const Symbols = require("./Symbols");
 
 /**
  * NRSubflow - Description
- * @property {object} instances - instances of the subflow
+ * @property {Map<String,NRSubflowInstance>} instances - instances of the subflow
+ * @property {String} category - if set, custom category this subflow is in
+ * @property {String} color - if set, custom color for this subflow node
+ * @property {String} icon - a custom icon for the subflow node, if set
+ * @property {String[]} inputLabels - array of custom labels for the node inputs
+ * @property {String[]} outputLabels - array of custom labels for the node outputs
+ * @property {object} env - subflow properties definition
+ * @property {object} meta - meta information about the subflow
+ *
  * @extends NRFlow
  */
 class NRSubflow extends NRFlow {