Rework jsdoc format and pull in jsdoc-nr-template

jsdoc.json

@@ -1,6 +1,6 @@
 {
     "opts": {
-        "template": "./node_modules/minami",
+        "template": "./node_modules/jsdoc-nr-template",
         "destination": "./docs",
         "recurse": true
     },
@@ -17,7 +17,10 @@
         "systemName": "Node-RED Runtime API",
         "theme":"yeti",
         "footer": "",
-        "copyright": "Released under the Apache License v2.0"
+        "copyright": "Released under the Apache License v2.0",
+        "default": {
+            "outputSourceFiles": false
+        }
     },
     "plugins": ["plugins/markdown"]
 }

package.json

@@ -106,7 +106,8 @@
         "wdio-mocha-framework": "^0.6.2",
         "wdio-spec-reporter": "^0.1.5",
         "webdriverio": "^4.13.1",
-        "node-red-node-test-helper": "node-red/node-red-node-test-helper"
+        "node-red-node-test-helper": "node-red/node-red-node-test-helper",
+        "jsdoc-nr-template": "node-red/jsdoc-nr-template"
     },
     "engines": {
         "node": ">=8"

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

@@ -15,7 +15,7 @@
  **/
 
  /**
-  * @namespace @node-red/util
+  * @module @node-red/util
   */
 const log = require("./lib/log");
 const i18n = require("./lib/i18n");
@@ -30,10 +30,19 @@ module.exports = {
         log.init(settings);
         i18n.init();
     },
+    /**
+    * Logging utilities
+    * @type module:@node-red/util-log
+    */
     log: log,
+    /**
+    * Internationalization utilities
+    * @type module:@node-red/util-i18n
+    */
     i18n: i18n,
     /**
     * General utilities
+    * @type module:@node-red/util-util
     */
     util: util
 }

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

@@ -20,11 +20,11 @@ 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 @node-red/util.util
+ * @memberof module:@node-red/util-util
  */
 function generateId() {
     return (1+Math.random()*4294967295).toString(16);
@@ -36,7 +36,7 @@ function generateId() {
  *
  * @param  {any}    o - the property to convert to a String
  * @return {String} the stringified version
- * @memberof @node-red/util.util
+ * @memberof module:@node-red/util-util
  */
 function ensureString(o) {
     if (Buffer.isBuffer(o)) {
@@ -55,7 +55,7 @@ function ensureString(o) {
  *
  * @param  {any}    o - the property to convert to a Buffer
  * @return {String} the Buffer version
- * @memberof @node-red/util.util
+ * @memberof module:@node-red/util-util
  */
 function ensureBuffer(o) {
     if (Buffer.isBuffer(o)) {
@@ -74,7 +74,7 @@ function ensureBuffer(o) {
  *
  * @param  {any}    msg - the message object to clone
  * @return {Object} the cloned message
- * @memberof @node-red/util.util
+ * @memberof module:@node-red/util-util
  */
 function cloneMessage(msg) {
     // Temporary fix for #97
@@ -101,7 +101,7 @@ function cloneMessage(msg) {
  * @param  {any}    obj1
  * @param  {any}    obj2
  * @return {boolean} whether the two objects are the same
- * @memberof @node-red/util.util
+ * @memberof module:@node-red/util-util
  */
 function compareObjects(obj1,obj2) {
     var i;
@@ -178,7 +178,7 @@ function compareObjects(obj1,obj2) {
  *
  * @param  {String} str - the property expression
  * @return {Array} the normalised expression
- * @memberof @node-red/util.util
+ * @memberof module:@node-red/util-util
  */
 function normalisePropertyExpression(str) {
     // This must be kept in sync with validatePropertyExpression
@@ -287,13 +287,13 @@ function normalisePropertyExpression(str) {
 /**
  * Gets a property of a message object.
  *
- * Unlike {@link @node-red/util.util.getObjectProperty}, this function will strip `msg.` from the
+ * Unlike {@link @node-red/util-util.getObjectProperty}, this function will strip `msg.` from the
  * front of the property expression if present.
  *
  * @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 @node-red/util.util
+ * @memberof module:@node-red/util-util
  */
 function getMessageProperty(msg,expr) {
     if (expr.indexOf('msg.')===0) {
@@ -308,7 +308,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 @node-red/util.util
+ * @memberof module:@node-red/util-util
  */
 function getObjectProperty(msg,expr) {
     var result = null;
@@ -324,14 +324,14 @@ function getObjectProperty(msg,expr) {
 /**
  * Sets a property of a message object.
  *
- * Unlike {@link @node-red/util.util.setObjectProperty}, this function will strip `msg.` from the
+ * Unlike {@link @node-red/util-util.setObjectProperty}, this function will strip `msg.` from the
  * front of the property expression if present.
  *
  * @param  {Object}  msg           - the message object
  * @param  {String}  prop          - the property expression
  * @param  {any}     value         - the value to set
  * @param  {boolean} createMissing - whether to create missing parent properties
- * @memberof @node-red/util.util
+ * @memberof module:@node-red/util-util
  */
 function setMessageProperty(msg,prop,value,createMissing) {
     if (prop.indexOf('msg.')===0) {
@@ -347,7 +347,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 @node-red/util.util
+ * @memberof module:@node-red/util-util
  */
 function setObjectProperty(msg,prop,value,createMissing) {
     if (typeof createMissing === 'undefined') {
@@ -411,7 +411,7 @@ function setObjectProperty(msg,prop,value,createMissing) {
  * will return `Hello Joe!`.
  * @param  {String} value - the string to parse
  * @return {String} The parsed string
-* @memberof @node-red/util.util
+* @memberof module:@node-red/util-util
  */
 function evaluateEnvProperty(value) {
     if (/^\${[^}]+}$/.test(value)) {
@@ -439,7 +439,7 @@ function evaluateEnvProperty(value) {
  *
  * @param  {String} value - the context property string to parse
  * @return {Object} The parsed property
- * @memberof @node-red/util.util
+ * @memberof module:@node-red/util-util
  */
 function parseContextStore(key) {
     var parts = {};
@@ -463,7 +463,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 @node-red/util.util
+ * @memberof module:@node-red/util-util
  */
 function evaluateNodeProperty(value, type, node, msg, callback) {
     var result = value;
@@ -520,7 +520,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 @node-red/util.util
+ * @memberof module:@node-red/util-util
  */
 function prepareJSONataExpression(value,node) {
     var expr = jsonata(value);
@@ -541,14 +541,14 @@ function prepareJSONataExpression(value,node) {
 
 /**
  * Evaluates a JSONata expression.
- * The expression must have been prepared with {@link @node-red/util.util.prepareJSONataExpression}
+ * The expression must have been prepared with {@link @node-red/util-util.prepareJSONataExpression}
  * before passing to this function.
  *
  * @param  {Object}   expr     - the prepared JSONata expression
  * @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 @node-red/util.util
+ * @memberof module:@node-red/util-util
  */
 function evaluateJSONataExpression(expr,msg,callback) {
     var context = msg;
@@ -593,7 +593,7 @@ function evaluateJSONataExpression(expr,msg,callback) {
  *
  * @param  {String} name - the node type
  * @return {String} The normalised name
- * @memberof @node-red/util.util
+ * @memberof module:@node-red/util-util
  */
 function normaliseNodeTypeName(name) {
     var result = name.replace(/[^a-zA-Z0-9]/g, " ");
@@ -617,7 +617,7 @@ function normaliseNodeTypeName(name) {
  * @param  {Object} msg
  * @param {Object} opts
  * @return {Object} the encoded object
- * @memberof @node-red/util.util
+ * @memberof module:@node-red/util-util
  */
 function encodeObject(msg,opts) {
     var debuglength = 1000;
@@ -748,8 +748,7 @@ function encodeObject(msg,opts) {
 
 /**
  * General utilities
- * @namespace util
- * @memberof @node-red/util
+ * @module @node-red/util-util
  */
 module.exports = {
     encodeObject: encodeObject,