Get jdsoc tagging right for util module

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

@@ -32,17 +32,17 @@ module.exports = {
     },
     /**
     * Logging utilities
-    * @type module:@node-red/util-log
+    * @see module:@node-red/util.module:log
     */
     log: log,
     /**
     * Internationalization utilities
-    * @type module:@node-red/util-i18n
+    * @see module:@node-red/util.module:i18n
     */
     i18n: i18n,
     /**
     * General utilities
-    * @type module:@node-red/util-util
+    * @see module:@node-red/util.module:util
     */
     util: util
 }

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

@@ -15,6 +15,11 @@
  * @ignore
  **/
 
+ /**
+  * @module i18n
+  * @memberof module:@node-red/util
+  */
+
 var i18n = require("i18next");
 
 var when = require("when");
@@ -27,6 +32,10 @@ var resourceMap = {};
 var resourceCache = {};
 var initPromise;
 
+/**
+ * Register multiple message catalogs with i18n.
+ * @memberof module:@node-red/util.module:i18n
+ */
 function registerMessageCatalogs(catalogs) {
     var promises = catalogs.map(function(catalog) {
         return registerMessageCatalog(catalog.namespace,catalog.dir,catalog.file);
@@ -34,6 +43,10 @@ function registerMessageCatalogs(catalogs) {
     return when.settle(promises);
 }
 
+/**
+ * Register a message catalog with i18n.
+ * @memberof module:@node-red/util.module:i18n
+ */
 function registerMessageCatalog(namespace,dir,file) {
     return initPromise.then(function() {
         return new Promise((resolve,reject) => {
@@ -128,6 +141,13 @@ function init() {
     }
 }
 
+
+/**
+ * Gets a message catalog.
+ * @name catalog
+ * @function
+ * @memberof module:@node-red/util.module:i18n
+ */
 function getCatalog(namespace,lang) {
     var result = null;
     lang = lang || defaultLang;
@@ -148,10 +168,22 @@ var obj = module.exports = {
     registerMessageCatalog: registerMessageCatalog,
     registerMessageCatalogs: registerMessageCatalogs,
     catalog: getCatalog,
+    /**
+     * The underlying i18n library for when direct access is really needed
+     */
     i: i18n,
+    /**
+     * The default language of the runtime
+     */
     defaultLang: defaultLang
 }
 
+/**
+ * Perform a message catalog lookup.
+ * @name _
+ * @function
+ * @memberof module:@node-red/util.module:i18n
+ */
 obj['_'] = function() {
     //var opts = {};
     //if (def) {

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

@@ -15,6 +15,11 @@
  * @ignore
  **/
 
+/**
+ * @module log
+ * @memberof module:@node-red/util
+ */
+
 var util = require("util");
 var EventEmitter = require("events").EventEmitter;
 
@@ -87,7 +92,9 @@ var consoleLogger = function(msg) {
     }
 }
 
+
 var log = module.exports = {
+
     FATAL:  10,
     ERROR:  20,
     WARN:   30,
@@ -119,40 +126,79 @@ var log = module.exports = {
             log.addHandler(new LogHandler());
         }
     },
+
+    /**
+     * Add a log handler function.
+     */
     addHandler: function(func) {
         logHandlers.push(func);
     },
+
+    /**
+     * Remove a log handler function.
+     */
     removeHandler: function(func) {
         var index = logHandlers.indexOf(func);
         if (index > -1) {
             logHandlers.splice(index,1);
         }
     },
+
+    /**
+     * Log a message object.
+     */
     log: function(msg) {
         msg.timestamp = Date.now();
         logHandlers.forEach(function(handler) {
             handler.emit("log",msg);
         });
     },
+
+    /**
+     * Log a message at INFO level.
+     */
     info: function(msg) {
         log.log({level:log.INFO,msg:msg});
     },
+
+    /**
+     * Log a message at WARN level.
+     */
     warn: function(msg) {
         log.log({level:log.WARN,msg:msg});
     },
+
+    /**
+     * Log a message at ERROR level.
+     */
     error: function(msg) {
         log.log({level:log.ERROR,msg:msg});
     },
+
+    /**
+     * Log a message at TRACE level.
+     */
     trace: function(msg) {
         log.log({level:log.TRACE,msg:msg});
     },
+
+    /**
+     * Log a message at DEBUG level.
+     */
     debug: function(msg) {
         log.log({level:log.DEBUG,msg:msg});
     },
+
+    /**
+     * Log a metric event.
+     */
     metric: function() {
         return metricsEnabled;
     },
 
+    /**
+     * Log an audit event.
+     */
     audit: function(msg,req) {
         msg.level = log.AUDIT;
         if (req) {
@@ -164,4 +210,10 @@ var log = module.exports = {
     }
 }
 
+/**
+ * Perform a message catalog lookup.
+ * @name _
+ * @function
+ * @memberof module:@node-red/util.module:log
+ */
 log["_"] = i18n._;

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

@@ -15,16 +15,21 @@
  * @ignore
  **/
 
+ /**
+  * @module util
+  * @memberof module:@node-red/util
+  */
+
+
 const clone = require("clone");
 const jsonata = require("jsonata");
 const safeJSONStringify = require("json-stringify-safe");
 const util = require("util");
 
-
 /**
  * Generates a psuedo-unique-random id.
  * @return {String} a random-ish id
- * @memberof module:@node-red/util-util
+ * @memberof module:@node-red/util.module:util
  */
 function generateId() {
     return (1+Math.random()*4294967295).toString(16);
@@ -36,7 +41,7 @@ function generateId() {
  *
  * @param  {any}    o - the property to convert to a String
  * @return {String} the stringified version
- * @memberof module:@node-red/util-util
+ * @memberof module:@node-red/util.module:util
  */
 function ensureString(o) {
     if (Buffer.isBuffer(o)) {
@@ -55,7 +60,7 @@ function ensureString(o) {
  *
  * @param  {any}    o - the property to convert to a Buffer
  * @return {String} the Buffer version
- * @memberof module:@node-red/util-util
+ * @memberof module:@node-red/util.module:util
  */
 function ensureBuffer(o) {
     if (Buffer.isBuffer(o)) {
@@ -74,7 +79,7 @@ function ensureBuffer(o) {
  *
  * @param  {any}    msg - the message object to clone
  * @return {Object} the cloned message
- * @memberof module:@node-red/util-util
+ * @memberof module:@node-red/util.module:util
  */
 function cloneMessage(msg) {
     // Temporary fix for #97
@@ -101,7 +106,7 @@ function cloneMessage(msg) {
  * @param  {any}    obj1
  * @param  {any}    obj2
  * @return {boolean} whether the two objects are the same
- * @memberof module:@node-red/util-util
+ * @memberof module:@node-red/util.module:util
  */
 function compareObjects(obj1,obj2) {
     var i;
@@ -178,7 +183,7 @@ function compareObjects(obj1,obj2) {
  *
  * @param  {String} str - the property expression
  * @return {Array} the normalised expression
- * @memberof module:@node-red/util-util
+ * @memberof module:@node-red/util.module:util
  */
 function normalisePropertyExpression(str) {
     // This must be kept in sync with validatePropertyExpression
@@ -293,7 +298,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-util
+ * @memberof module:@node-red/util.module:util
  */
 function getMessageProperty(msg,expr) {
     if (expr.indexOf('msg.')===0) {
@@ -308,7 +313,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-util
+ * @memberof module:@node-red/util.module:util
  */
 function getObjectProperty(msg,expr) {
     var result = null;
@@ -331,7 +336,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-util
+ * @memberof module:@node-red/util.module:util
  */
 function setMessageProperty(msg,prop,value,createMissing) {
     if (prop.indexOf('msg.')===0) {
@@ -347,7 +352,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-util
+ * @memberof module:@node-red/util.module:util
  */
 function setObjectProperty(msg,prop,value,createMissing) {
     if (typeof createMissing === 'undefined') {
@@ -411,7 +416,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-util
+* @memberof module:@node-red/util.module:util
  */
 function evaluateEnvProperty(value) {
     if (/^\${[^}]+}$/.test(value)) {
@@ -439,7 +444,7 @@ function evaluateEnvProperty(value) {
  *
  * @param  {String} value - the context property string to parse
  * @return {Object} The parsed property
- * @memberof module:@node-red/util-util
+ * @memberof module:@node-red/util.module:util
  */
 function parseContextStore(key) {
     var parts = {};
@@ -463,7 +468,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-util
+ * @memberof module:@node-red/util.module:util
  */
 function evaluateNodeProperty(value, type, node, msg, callback) {
     var result = value;
@@ -520,7 +525,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-util
+ * @memberof module:@node-red/util.module:util
  */
 function prepareJSONataExpression(value,node) {
     var expr = jsonata(value);
@@ -548,7 +553,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-util
+ * @memberof module:@node-red/util.module:util
  */
 function evaluateJSONataExpression(expr,msg,callback) {
     var context = msg;
@@ -593,7 +598,7 @@ function evaluateJSONataExpression(expr,msg,callback) {
  *
  * @param  {String} name - the node type
  * @return {String} The normalised name
- * @memberof module:@node-red/util-util
+ * @memberof module:@node-red/util.module:util
  */
 function normaliseNodeTypeName(name) {
     var result = name.replace(/[^a-zA-Z0-9]/g, " ");
@@ -617,7 +622,7 @@ function normaliseNodeTypeName(name) {
  * @param  {Object} msg
  * @param {Object} opts
  * @return {Object} the encoded object
- * @memberof module:@node-red/util-util
+ * @memberof module:@node-red/util.module:util
  */
 function encodeObject(msg,opts) {
     var debuglength = 1000;
@@ -746,10 +751,6 @@ function encodeObject(msg,opts) {
     return msg;
 }
 
-/**
- * General utilities
- * @module @node-red/util-util
- */
 module.exports = {
     encodeObject: encodeObject,
     ensureString: ensureString,