Documentation updates for node-red and runtime modules

packages/node_modules/node-red/lib/red.js

@@ -1,4 +1,4 @@
-/**
+/*!
  * Copyright JS Foundation and other contributors, http://js.foundation
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -22,8 +22,6 @@ var redUtil = require("@node-red/util");
 
 var api = require("@node-red/editor-api");
 
-var nodeApp = null;
-var adminApp = null;
 var server = null;
 var apiEnabled = false;
 
@@ -37,9 +35,20 @@ function checkVersion(userSettings) {
         userSettings.UNSUPPORTED_VERSION = process.version;
     }
 }
-
+/**
+ * This module provides the full Node-RED application, with both the runtime
+ * and editor components built in.
+ *
+ * @namespace node-red
+ */
 module.exports = {
-    init: function(httpServer,userSettings) {
+    /**
+     * Initialise the Node-RED application.
+     * @param {server} httpServer - the HTTP server object to use
+     * @param {Object} userSettings - an object containing the runtime settings
+     * @memberof node-red
+     */
+    init: function(httpServer, userSettings) {
         if (!userSettings) {
             userSettings = httpServer;
             httpServer = null;
@@ -54,27 +63,26 @@ module.exports = {
         }
         redUtil.init(userSettings);
         if (userSettings.httpAdminRoot !== false) {
-            runtime.init(userSettings,api);
-            api.init(httpServer,userSettings,runtime._.storage,runtime);
-
+            runtime.init(userSettings,httpServer,api);
+            api.init(userSettings,httpServer,runtime.storage,runtime);
             apiEnabled = true;
-            server = runtime._.adminApi.server;
-            runtime._.server = runtime._.adminApi.server;
+            server = httpServer;
         } else {
             runtime.init(userSettings);
             apiEnabled = false;
-            if (httpServer){
+            if (httpServer) {
                 server = httpServer;
-                runtime._.server = httpServer;
             } else {
-                server = runtime._.adminApi.server;
-                runtime._.server = runtime._.adminApi.server; // useless at this point, but at least harmless.
+                server = null;
             }
         }
-        adminApp = runtime._.adminApi.adminApp;
-        nodeApp = runtime._.nodeApp;
         return;
     },
+    /**
+     * Start the Node-RED application.
+     * @return {Promise} - resolves when complete
+     * @memberof node-red
+     */
     start: function() {
         return runtime.start().then(function() {
             if (apiEnabled) {
@@ -82,6 +90,11 @@ module.exports = {
             }
         });
     },
+    /**
+     * Stop the Node-RED application.
+     * @return {Promise} - resolves when complete
+     * @memberof node-red
+     */
     stop: function() {
         return runtime.stop().then(function() {
             if (apiEnabled) {
@@ -89,30 +102,37 @@ module.exports = {
             }
         })
     },
-    nodes: runtime._.nodes,
-    log: redUtil.log,
-    settings:runtime._.settings,
-    util: runtime._.util,
-    version: runtime._.version,
-    events: runtime._.events,
-    comms: {
-        publish: function(topic,data,retain) {
-            runtime._.events.emit("comms",{
-                topic: topic,
-                data: data,
-                retain: retain
-            })
-        }
-    },
-    library: {
-        register: function(type) {
-            return runtime._.library.register(null,type);
-        }
-    },
-    auth: api.auth,
 
-    get app() { console.log("Deprecated use of RED.app - use RED.httpAdmin instead"); return runtime._.app },
-    get httpAdmin() { return adminApp },
-    get httpNode() { return nodeApp },
-    get server() { return server }
+    log: redUtil.log,
+    util: redUtil.util,
+
+    get nodes() { console.log("Deprecated use of RED.nodes - refer to API documentation on RED.runtime.nodes"); return runtime._.nodes },
+    get settings() { console.log("Deprecated use of RED.settings - refer to API documentation on RED.runtime.settings"); return runtime._.settings },
+    get version() { console.log("Deprecated use of RED.version - refer to API documentation on RED.runtime.version"); return runtime._.version },
+    get events() { console.log("Deprecated use of RED.events - refer to API documentation on RED.runtime.events"); return runtime.events },
+
+    /**
+     * The express application for the Editor Admin API
+     * @memberof node-red
+     */
+    get httpAdmin() { return api.adminApp },
+
+    /**
+     * The express application for HTTP Nodes
+     * @memberof node-red
+     */
+    get httpNode() { return runtime.httpNode },
+
+    /**
+     * The HTTP Server used by the runtime
+     * @memberof node-red
+     */
+    get server() { return server },
+
+    /**
+     * The runtime api
+     * @see @node-red/runtime
+     * @memberof node-red
+     */
+    runtime: runtime
 };