Documentation updates for node-red and runtime modules

packages/node_modules/@node-red/runtime/lib/index.js

@@ -1,4 +1,4 @@
-/**
+/*!
  * Copyright JS Foundation and other contributors, http://js.foundation
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -31,8 +31,8 @@ var fs = require("fs");
 var os = require("os");
 
 var redUtil = require("@node-red/util");
-var log;
-var i18n;
+var log = redUtil.log;
+var i18n = redUtil.i18n;
 
 var runtimeMetricInterval = null;
 
@@ -48,18 +48,24 @@ var adminApi = {
     auth: {
         needsPermission: function() {}
     },
-    comms: {
-        publish: function() {}
-    },
     adminApp: stubbedExpressApp,
     server: {}
 }
 
 var nodeApp;
+var server;
 
-function init(userSettings,_adminApi) {
-    log = redUtil.log;
-    i18n = redUtil.i18n;
+
+/**
+ * Initialise the runtime module.
+ * @param {Object} settings - the runtime settings object
+ * @param {HTTPServer} server - the http server instance for the server to use
+ * @param {AdminAPI} adminApi - an instance of @node-red/editor-api. <B>TODO</B>: This needs to be
+ *                              better abstracted.
+ * @memberof @node-red/runtime
+ */
+function init(userSettings,httpServer,_adminApi) {
+    server = httpServer;
     userSettings.version = getVersion();
     settings.init(userSettings);
 
@@ -90,6 +96,12 @@ function getVersion() {
     return version;
 }
 
+/**
+ * Start the runtime.
+ * @return {Promise} - resolves when the runtime is started. This does not mean the
+ *   flows will be running as they are started asynchronously.
+ * @memberof @node-red/runtime
+ */
 function start() {
 
     return i18n.registerMessageCatalog("runtime",path.resolve(path.join(__dirname,"..","locales")),"runtime.json")
@@ -225,6 +237,11 @@ function reportMetrics() {
     });
 }
 
+/**
+ * Stops the runtime.
+ * @return {Promise} - resolves when the runtime is stopped.
+ * @memberof @node-red/runtime
+ */
 function stop() {
     if (runtimeMetricInterval) {
         clearInterval(runtimeMetricInterval);
@@ -253,27 +270,89 @@ var runtime = {
     util: require("@node-red/util").util,
     get adminApi() { return adminApi },
     get nodeApp() { return nodeApp },
+    get server() { return server },
     isStarted: function() {
         return started;
     }
 };
 
-
+/**
+ * This module provides the core runtime component of Node-RED.
+ * It does *not* include the Node-RED editor. All interaction with
+ * this module is done using the api provided.
+ *
+ * @namespace @node-red/runtime
+ */
 module.exports = {
     init: init,
     start: start,
     stop: stop,
 
-    "_": runtime,
-
+    /**
+    * @memberof @node-red/runtime
+    * @mixes @node-red/runtime_comms
+    */
     comms: externalAPI.comms,
+    /**
+    * @memberof @node-red/runtime
+    * @mixes @node-red/runtime_flows
+    */
     flows: externalAPI.flows,
+    /**
+    * @memberof @node-red/runtime
+    * @mixes @node-red/runtime_library
+    */
     library: externalAPI.library,
+    /**
+    * @memberof @node-red/runtime
+    * @mixes @node-red/runtime_nodes
+    */
     nodes: externalAPI.nodes,
+    /**
+    * @memberof @node-red/runtime
+    * @mixes @node-red/runtime_settings
+    */
     settings: externalAPI.settings,
+    /**
+    * @memberof @node-red/runtime
+    * @mixes @node-red/runtime_projects
+    */
     projects: externalAPI.projects,
+    /**
+    * @memberof @node-red/runtime
+    * @mixes @node-red/runtime_context
+    */
     context: externalAPI.context,
 
+    /**
+    * Returns whether the runtime is started
+    * @param {Object} opts
+    * @param {User} opts.user - the user calling the api
+    * @return {Promise<Boolean>} - whether the runtime is started
+    * @function
+    * @memberof @node-red/runtime
+    */
     isStarted: externalAPI.isStarted,
-    version: externalAPI.version
+
+    /**
+    * Returns version number of the runtime
+    * @param {Object} opts
+    * @param {User} opts.user - the user calling the api
+    * @return {Promise<String>} - the runtime version number
+    * @function
+    * @memberof @node-red/runtime
+    */
+    version: externalAPI.version,
+
+    storage: storage,
+    events: events,
+    get httpNode() { return nodeApp },
+    get server() { return server }
 }
+
+
+/**
+ * A user accessing the API
+ * @typedef User
+ * @type {object}
+ */