From 48308db45b534257a99e48d39af5efad97eebb1a Mon Sep 17 00:00:00 2001 From: Nick O'Leary Date: Fri, 24 Aug 2018 13:02:06 +0100 Subject: [PATCH] Rework jsdoc format and pull in jsdoc-nr-template --- jsdoc.json | 7 ++- package.json | 3 +- packages/node_modules/@node-red/util/index.js | 11 ++++- .../node_modules/@node-red/util/lib/util.js | 45 +++++++++---------- 4 files changed, 39 insertions(+), 27 deletions(-) diff --git a/jsdoc.json b/jsdoc.json index 2a50b016a..dca8b7e26 100644 --- a/jsdoc.json +++ b/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"] } diff --git a/package.json b/package.json index 1e594e932..f36b12834 100644 --- a/package.json +++ b/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" diff --git a/packages/node_modules/@node-red/util/index.js b/packages/node_modules/@node-red/util/index.js index f2804fedf..e10098b18 100644 --- a/packages/node_modules/@node-red/util/index.js +++ b/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 } diff --git a/packages/node_modules/@node-red/util/lib/util.js b/packages/node_modules/@node-red/util/lib/util.js index ac777958f..cb0660e24 100644 --- a/packages/node_modules/@node-red/util/lib/util.js +++ b/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,