API documentation updates

Gruntfile.js

@@ -429,23 +429,18 @@ module.exports = function(grunt) {
             }
         },
         jsdoc : {
-            runtimeAPI: {
+            modules: {
                 src: [
                     'packages/node_modules/node-red/lib/red.js',
                     'packages/node_modules/@node-red/runtime/lib/index.js',
                     'packages/node_modules/@node-red/runtime/lib/api/*.js',
+                    'packages/node_modules/@node-red/runtime/lib/events.js',
+                    'packages/node_modules/@node-red/util/**/*.js',
                     ],
                 options: {
                     destination: 'docs',
                     configure: './jsdoc.json'
                 }
-            },
-            nodeREDUtil: {
-                src: 'packages/node_modules/@node-red/util/**/*.js',
-                options: {
-                    destination: 'packages/node_modules/@node-red/util/docs',
-                    configure: './jsdoc.json'
-                }
             }
         },
         jsdoc2md: {
@@ -453,8 +448,11 @@ module.exports = function(grunt) {
                 options: {
                     separators: true
                 },
-                src: ['packages/node_modules/@node-red/runtime/lib/index.js',
-                      'packages/node_modules/@node-red/runtime/lib/api/*.js'],
+                src: [
+                    'packages/node_modules/@node-red/runtime/lib/index.js',
+                    'packages/node_modules/@node-red/runtime/lib/api/*.js',
+                    'packages/node_modules/@node-red/runtime/lib/events.js'
+                ],
                 dest: 'packages/node_modules/@node-red/runtime/docs/api.md'
             },
             nodeREDUtil: {

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

@@ -1,4 +1,4 @@
-/**
+/*!
  * Copyright JS Foundation and other contributors, http://js.foundation
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,6 +14,30 @@
  * limitations under the License.
  **/
 
-var events = require("events"); 
+var events = require("events");
 
-module.exports = new events.EventEmitter(); 
+module.exports = new events.EventEmitter();
+
+/**
+ * Runtime events emitter
+ * @mixin @node-red/runtime_events
+ */
+
+/**
+ * Register an event listener for a runtime event
+ * @name on
+ * @function
+ * @memberof @node-red/runtime_events
+ * @param {String} eventName - the name of the event to listen to
+ * @param {Function} listener - the callback function for the event
+ */
+
+ /**
+  * Emit an event to all of its registered listeners
+  * @name emit
+  * @function
+  * @memberof @node-red/runtime_events
+  * @param {String} eventName - the name of the event to emit
+  * @param {any} ...args - the arguments to pass in the event
+  * @return {Boolean} - whether the event had listeners or not
+  */

packages/node_modules/@node-red/util/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");
@@ -14,17 +14,20 @@
  * limitations under the License.
  **/
 
- /**
-  * @module @node-red/util
-  */
 const log = require("./lib/log");
 const i18n = require("./lib/i18n");
 const util = require("./lib/util");
 
+/**
+ * This module provides common utilities for the Node-RED runtime and editor
+ *
+ * @namespace @node-red/util
+ */
 module.exports = {
     /**
     * Initialise the module with the runtime settings
     * @param {Object} settings
+    * @memberof @node-red/util
     */
     init: function(settings) {
         log.init(settings);
@@ -33,19 +36,22 @@ module.exports = {
 
     /**
     * Logging utilities
-    * @see module:@node-red/util.module:log
+    * @mixes @node-red/util_log
+    * @memberof @node-red/util
     */
     log: log,
 
     /**
     * Internationalization utilities
-    * @see module:@node-red/util.module:i18n
+    * @mixes @node-red/util_i18n
+    * @memberof @node-red/util
     */
     i18n: i18n,
 
     /**
     * General utilities
-    * @see module:@node-red/util.module:util
+    * @mixes @node-red/util_util
+    * @memberof @node-red/util
     */
     util: util,
 }

packages/node_modules/@node-red/util/lib/i18n.js

@@ -15,10 +15,10 @@
  * @ignore
  **/
 
- /**
-  * @module i18n
-  * @memberof module:@node-red/util
-  */
+/**
+ * Internationalization utilities
+ * @mixin @node-red/util_i18n
+ */
 
 var i18n = require("i18next");
 
@@ -34,7 +34,7 @@ var initPromise;
 
 /**
  * Register multiple message catalogs with i18n.
- * @memberof module:@node-red/util.module:i18n
+ * @memberof @node-red/util_i18n
  */
 function registerMessageCatalogs(catalogs) {
     var promises = catalogs.map(function(catalog) {
@@ -45,7 +45,7 @@ function registerMessageCatalogs(catalogs) {
 
 /**
  * Register a message catalog with i18n.
- * @memberof module:@node-red/util.module:i18n
+ * @memberof @node-red/util_i18n
  */
 function registerMessageCatalog(namespace,dir,file) {
     return initPromise.then(function() {
@@ -146,7 +146,7 @@ function init() {
  * Gets a message catalog.
  * @name catalog
  * @function
- * @memberof module:@node-red/util.module:i18n
+ * @memberof @node-red/util_i18n
  */
 function getCatalog(namespace,lang) {
     var result = null;
@@ -182,7 +182,7 @@ var obj = module.exports = {
  * Perform a message catalog lookup.
  * @name _
  * @function
- * @memberof module:@node-red/util.module:i18n
+ * @memberof @node-red/util_i18n
  */
 obj['_'] = function() {
     //var opts = {};

packages/node_modules/@node-red/util/lib/log.js

@@ -16,8 +16,8 @@
  **/
 
 /**
- * @module log
- * @memberof module:@node-red/util
+ * Logging utilities
+ * @mixin @node-red/util_log
  */
 
 var util = require("util");
@@ -128,14 +128,16 @@ var log = module.exports = {
     },
 
     /**
-     * Add a log handler function.
+     * Add a log handler function
+     * @memberof @node-red/util_log
      */
     addHandler: function(func) {
         logHandlers.push(func);
     },
 
     /**
-     * Remove a log handler function.
+     * Remove a log handler function
+     * @memberof @node-red/util_log
      */
     removeHandler: function(func) {
         var index = logHandlers.indexOf(func);
@@ -145,7 +147,8 @@ var log = module.exports = {
     },
 
     /**
-     * Log a message object.
+     * Log a message object
+     * @memberof @node-red/util_log
      */
     log: function(msg) {
         msg.timestamp = Date.now();
@@ -155,42 +158,48 @@ var log = module.exports = {
     },
 
     /**
-     * Log a message at INFO level.
+     * Log a message at INFO level
+     * @memberof @node-red/util_log
      */
     info: function(msg) {
         log.log({level:log.INFO,msg:msg});
     },
 
     /**
-     * Log a message at WARN level.
+     * Log a message at WARN level
+     * @memberof @node-red/util_log
      */
     warn: function(msg) {
         log.log({level:log.WARN,msg:msg});
     },
 
     /**
-     * Log a message at ERROR level.
+     * Log a message at ERROR level
+     * @memberof @node-red/util_log
      */
     error: function(msg) {
         log.log({level:log.ERROR,msg:msg});
     },
 
     /**
-     * Log a message at TRACE level.
+     * Log a message at TRACE level
+     * @memberof @node-red/util_log
      */
     trace: function(msg) {
         log.log({level:log.TRACE,msg:msg});
     },
 
     /**
-     * Log a message at DEBUG level.
+     * Log a message at DEBUG level
+     * @memberof @node-red/util_log
      */
     debug: function(msg) {
         log.log({level:log.DEBUG,msg:msg});
     },
 
     /**
-     * Log a metric event.
+     * Check if metrics are enabled
+     * @memberof @node-red/util_log
      */
     metric: function() {
         return metricsEnabled;
@@ -198,6 +207,7 @@ var log = module.exports = {
 
     /**
      * Log an audit event.
+     * @memberof @node-red/util_log
      */
     audit: function(msg,req) {
         msg.level = log.AUDIT;
@@ -214,6 +224,6 @@ var log = module.exports = {
  * Perform a message catalog lookup.
  * @name _
  * @function
- * @memberof module:@node-red/util.module:log
+ * @memberof @node-red/util_log
  */
 log["_"] = i18n._;

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

@@ -15,10 +15,9 @@
  * @ignore
  **/
 
- /**
-  * @module util
-  * @memberof module:@node-red/util
-  */
+/**
+ * @mixin @node-red/util_util
+ */
 
 
 const clone = require("clone");
@@ -29,7 +28,7 @@ const util = require("util");
 /**
  * Generates a psuedo-unique-random id.
  * @return {String} a random-ish id
- * @memberof module:@node-red/util.module:util
+ * @memberof @node-red/util_util
  */
 function generateId() {
     return (1+Math.random()*4294967295).toString(16);
@@ -41,7 +40,7 @@ function generateId() {
  *
  * @param  {any}    o - the property to convert to a String
  * @return {String} the stringified version
- * @memberof module:@node-red/util.module:util
+ * @memberof @node-red/util_util
  */
 function ensureString(o) {
     if (Buffer.isBuffer(o)) {
@@ -60,7 +59,7 @@ function ensureString(o) {
  *
  * @param  {any}    o - the property to convert to a Buffer
  * @return {String} the Buffer version
- * @memberof module:@node-red/util.module:util
+ * @memberof @node-red/util_util
  */
 function ensureBuffer(o) {
     if (Buffer.isBuffer(o)) {
@@ -79,7 +78,7 @@ function ensureBuffer(o) {
  *
  * @param  {any}    msg - the message object to clone
  * @return {Object} the cloned message
- * @memberof module:@node-red/util.module:util
+ * @memberof @node-red/util_util
  */
 function cloneMessage(msg) {
     // Temporary fix for #97
@@ -106,7 +105,7 @@ function cloneMessage(msg) {
  * @param  {any}    obj1
  * @param  {any}    obj2
  * @return {boolean} whether the two objects are the same
- * @memberof module:@node-red/util.module:util
+ * @memberof @node-red/util_util
  */
 function compareObjects(obj1,obj2) {
     var i;
@@ -189,7 +188,7 @@ function createError(code, message) {
  *
  * @param  {String} str - the property expression
  * @return {Array} the normalised expression
- * @memberof module:@node-red/util.module:util
+ * @memberof @node-red/util_util
  */
 function normalisePropertyExpression(str) {
     // This must be kept in sync with validatePropertyExpression
@@ -304,7 +303,7 @@ function normalisePropertyExpression(str) {
  * @param  {Object} msg - the message object
  * @param  {String} str - the property expression
  * @return {any} the message property, or undefined if it does not exist
- * @memberof module:@node-red/util.module:util
+ * @memberof @node-red/util_util
  */
 function getMessageProperty(msg,expr) {
     if (expr.indexOf('msg.')===0) {
@@ -319,7 +318,7 @@ function getMessageProperty(msg,expr) {
  * @param  {Object} msg - the object
  * @param  {String} str - the property expression
  * @return {any} the object property, or undefined if it does not exist
- * @memberof module:@node-red/util.module:util
+ * @memberof @node-red/util_util
  */
 function getObjectProperty(msg,expr) {
     var result = null;
@@ -342,7 +341,7 @@ function getObjectProperty(msg,expr) {
  * @param  {String}  prop          - the property expression
  * @param  {any}     value         - the value to set
  * @param  {boolean} createMissing - whether to create missing parent properties
- * @memberof module:@node-red/util.module:util
+ * @memberof @node-red/util_util
  */
 function setMessageProperty(msg,prop,value,createMissing) {
     if (prop.indexOf('msg.')===0) {
@@ -358,7 +357,7 @@ function setMessageProperty(msg,prop,value,createMissing) {
  * @param  {String}  prop          - the property expression
  * @param  {any}     value         - the value to set
  * @param  {boolean} createMissing - whether to create missing parent properties
- * @memberof module:@node-red/util.module:util
+ * @memberof @node-red/util_util
  */
 function setObjectProperty(msg,prop,value,createMissing) {
     if (typeof createMissing === 'undefined') {
@@ -422,7 +421,7 @@ function setObjectProperty(msg,prop,value,createMissing) {
  * will return `Hello Joe!`.
  * @param  {String} value - the string to parse
  * @return {String} The parsed string
-* @memberof module:@node-red/util.module:util
+* @memberof @node-red/util_util
  */
 function evaluateEnvProperty(value) {
     if (/^\${[^}]+}$/.test(value)) {
@@ -450,7 +449,7 @@ function evaluateEnvProperty(value) {
  *
  * @param  {String} value - the context property string to parse
  * @return {Object} The parsed property
- * @memberof module:@node-red/util.module:util
+ * @memberof @node-red/util_util
  */
 function parseContextStore(key) {
     var parts = {};
@@ -474,7 +473,7 @@ function parseContextStore(key) {
  * @param  {Object}   msg      - the message object to evaluate against
  * @param  {Function} callback - (optional) called when the property is evaluated
  * @return {any} The evaluted property, if no `callback` is provided
- * @memberof module:@node-red/util.module:util
+ * @memberof @node-red/util_util
  */
 function evaluateNodeProperty(value, type, node, msg, callback) {
     var result = value;
@@ -531,7 +530,7 @@ function evaluateNodeProperty(value, type, node, msg, callback) {
  * @param  {String} value - the JSONata expression
  * @param  {Node}   node  - the node evaluating the property
  * @return {Object} The JSONata expression that can be evaluated
- * @memberof module:@node-red/util.module:util
+ * @memberof @node-red/util_util
  */
 function prepareJSONataExpression(value,node) {
     var expr = jsonata(value);
@@ -559,7 +558,7 @@ function prepareJSONataExpression(value,node) {
  * @param  {Object}   msg      - the message object to evaluate against
  * @param  {Function} callback - (optional) called when the expression is evaluated
  * @return {any} If no callback was provided, the result of the expression
- * @memberof module:@node-red/util.module:util
+ * @memberof @node-red/util_util
  */
 function evaluateJSONataExpression(expr,msg,callback) {
     var context = msg;
@@ -604,7 +603,7 @@ function evaluateJSONataExpression(expr,msg,callback) {
  *
  * @param  {String} name - the node type
  * @return {String} The normalised name
- * @memberof module:@node-red/util.module:util
+ * @memberof @node-red/util_util
  */
 function normaliseNodeTypeName(name) {
     var result = name.replace(/[^a-zA-Z0-9]/g, " ");
@@ -628,7 +627,7 @@ function normaliseNodeTypeName(name) {
  * @param  {Object} msg
  * @param {Object} opts
  * @return {Object} the encoded object
- * @memberof module:@node-red/util.module:util
+ * @memberof @node-red/util_util
  */
 function encodeObject(msg,opts) {
     var debuglength = 1000;

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

@@ -108,13 +108,38 @@ module.exports = {
         })
     },
 
+    /**
+     * Logging utilities
+     * @see @node-red/util_log
+     * @memberof node-red
+     */
     log: redUtil.log,
+
+    /**
+     * General utilities
+     * @see @node-red/util_util
+     * @memberof node-red
+     */
     util: redUtil.util,
 
     get nodes() { console.log("Deprecated use of RED.nodes - refer to API documentation on RED.runtime.nodes"); return runtime._.nodes },
-    get events() { console.log("Deprecated use of RED.events - refer to API documentation on RED.runtime.events"); return runtime.events },
+
+    /**
+     * Runtime events emitter
+     * @see @node-red/runtime_events
+     * @memberof node-red
+     */
+    events: runtime.events,
 
     get settings() { return runtime._.settings },
+
+
+    /**
+     * Get the version of the runtime
+     * @return {String} - the runtime version
+     * @function
+     * @memberof node-red
+     */
     get version() { return runtime._.version },