Add some function-level docs

red/nodes/flows.js

@@ -41,10 +41,15 @@ events.on('type-registered',function(type) {
         }
 });
 
-var parseConfig = function() {
+/**
+ * Parses the current activeConfig and creates the required node instances
+ */ 
+function parseConfig() {
     var i;
     var nt;
     missingTypes = [];
+    
+    // Scan the configuration for any unknown node types
     for (i=0;i<activeConfig.length;i++) {
         var type = activeConfig[i].type;
         // TODO: remove workspace in next release+1
@@ -55,6 +60,7 @@ var parseConfig = function() {
             }
         }
     }
+    // Abort if there are any missing types
     if (missingTypes.length > 0) {
         util.log("[red] Waiting for missing types to be registered:");
         for (i=0;i<missingTypes.length;i++) {
@@ -65,6 +71,8 @@ var parseConfig = function() {
 
     util.log("[red] Starting flows");
     events.emit("nodes-starting");
+    
+    // Instantiate each node in the flow
     for (i=0;i<activeConfig.length;i++) {
         var nn = null;
         // TODO: remove workspace in next release+1
@@ -89,7 +97,9 @@ var parseConfig = function() {
     events.emit("nodes-started");
 };
 
-
+/**
+ * Stops the current activeConfig
+ */
 function stopFlows() {
     if (activeConfig&&activeConfig.length > 0) {
         util.log("[red] Stopping flows");
@@ -101,6 +111,11 @@ var flowNodes = module.exports = {
     init: function(_storage) {
         storage = _storage;
     },
+    
+    /**
+     * Load the current activeConfig from storage and start it running
+     * @return a promise for the loading of the config
+     */
     load: function() {
         return storage.getFlows().then(function(flows) {
             return credentials.load().then(function() {
@@ -113,13 +128,29 @@ var flowNodes = module.exports = {
             util.log("[red] Error loading flows : "+err);
         });
     },
+    
+    /**
+     * Add a node to the current active set
+     * @param n the node to add
+     */
     add: function(n) {
         nodes[n.id] = n;
         n.on("log",log.log);
     },
+    
+    /**
+     * Get a node
+     * @param i the node id
+     * @return the node
+     */
     get: function(i) {
         return nodes[i];
     },
+    
+    /**
+     * Stops all active nodes and clears the active set
+     * @return a promise for the stopping of all active nodes
+     */
     clear: function() {
         return when.promise(function(resolve) {
             events.emit("nodes-stopping");
@@ -143,6 +174,11 @@ var flowNodes = module.exports = {
             });
         });
     },
+    
+    /**
+     * Provides an iterator over the active set of nodes
+     * @param cb a function to be called for each node in the active set
+     */
     each: function(cb) {
         for (var n in nodes) {
             if (nodes.hasOwnProperty(n)) {
@@ -151,9 +187,18 @@ var flowNodes = module.exports = {
         }
     },
 
+    /**
+     * @return the active configuration
+     */
     getFlows: function() {
         return activeConfig;
     },
+    
+    /**
+     * Sets the current active config.
+     * @param config the configuration to enable
+     * @return a promise for the starting of the new flow
+     */
     setFlows: function (config) {
         // Extract any credential updates
         for (var i=0; i<config.length; i++) {

red/nodes/index.js

@@ -31,6 +31,12 @@ function registerType(type,constructor,opts) {
     registry.registerType(type,constructor);    
 }
 
+/**
+ * Called from a Node's constructor function, invokes the super-class
+ * constructor and attaches any credentials to the node.
+ * @param node the node object being created
+ * @param def the instance definition for the node 
+ */
 function createNode(node,def) {
     Node.call(node,def);
     var creds = credentials.get(node.id);
@@ -45,24 +51,27 @@ function init(_settings,storage) {
     registry.init(_settings);
 }
 
-
 module.exports = {
+    // Lifecycle
     init: init,
     load: registry.load,
     
+    // Node registry
     createNode: createNode,
-    registerType: registerType,
-    
-    getType: registry.get,
-    getNodeConfigs: registry.getNodeConfigs,
     getNode: flows.get,
     
+    // Node type registry
+    registerType: registerType,
+    getType: registry.get,
+    getNodeConfigs: registry.getNodeConfigs,
+    
+    // Flow handling
     loadFlows: flows.load,
     stopFlows: flows.stopFlows,
     setFlows: flows.setFlows,
     getFlows: flows.getFlows,
     
-    // TODO: remove these from api - see #93
+    // Credentials
     addCredentials: credentials.add,
     getCredentials: credentials.get,
     deleteCredentials: credentials.delete