From 8e1c15419cd8aca1d57b08393dcb005a1008aae2 Mon Sep 17 00:00:00 2001 From: Nick O'Leary Date: Wed, 5 Dec 2018 13:00:25 +0000 Subject: [PATCH] API documentation updates --- Gruntfile.js | 18 ++++---- .../@node-red/runtime/lib/events.js | 30 ++++++++++++-- packages/node_modules/@node-red/util/index.js | 20 +++++---- .../node_modules/@node-red/util/lib/i18n.js | 16 ++++---- .../node_modules/@node-red/util/lib/log.js | 34 +++++++++------ .../node_modules/@node-red/util/lib/util.js | 41 +++++++++---------- packages/node_modules/node-red/lib/red.js | 27 +++++++++++- 7 files changed, 124 insertions(+), 62 deletions(-) diff --git a/Gruntfile.js b/Gruntfile.js index ee49ae9eb..eae2587ef 100644 --- a/Gruntfile.js +++ b/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: { diff --git a/packages/node_modules/@node-red/runtime/lib/events.js b/packages/node_modules/@node-red/runtime/lib/events.js index d1f2bc820..ed280a618 100644 --- a/packages/node_modules/@node-red/runtime/lib/events.js +++ b/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 + */ diff --git a/packages/node_modules/@node-red/util/index.js b/packages/node_modules/@node-red/util/index.js index cc7f502f8..66ac91bd3 100644 --- a/packages/node_modules/@node-red/util/index.js +++ b/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, } diff --git a/packages/node_modules/@node-red/util/lib/i18n.js b/packages/node_modules/@node-red/util/lib/i18n.js index 07f534dff..6dc707237 100644 --- a/packages/node_modules/@node-red/util/lib/i18n.js +++ b/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 = {}; diff --git a/packages/node_modules/@node-red/util/lib/log.js b/packages/node_modules/@node-red/util/lib/log.js index 8c52e3ed9..abce5fa99 100644 --- a/packages/node_modules/@node-red/util/lib/log.js +++ b/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._; diff --git a/packages/node_modules/@node-red/util/lib/util.js b/packages/node_modules/@node-red/util/lib/util.js index 9c9c344d9..8aec3b9f1 100644 --- a/packages/node_modules/@node-red/util/lib/util.js +++ b/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; diff --git a/packages/node_modules/node-red/lib/red.js b/packages/node_modules/node-red/lib/red.js index 6d052217a..1f8b8dd11 100644 --- a/packages/node_modules/node-red/lib/red.js +++ b/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 },