I found out about jsdoc and wanted to use it to document my node-red flows, however after setting it up I learnt a bit more about how node-red stores the code inside flows.
Out of the box the format is not compatible with jsdoc - at least I don't know how to get it to work.
jsdoc appears to be looking for comments in code e.g.
/**
* variableName
* @type {string}
*/
but node-red seems to store the same information (in the flows.json) as this:
I got a little overexcited at the prospect of using jsdoc to create a documentation website
Hoping someone has done this before, else I'll dig-in and do some more research.
PS: I have read some posts on various was to building the documentation directly into your flows directly and use the tools built into Node-Red.
Maybe that is the path I have to go down, but I really liked the idea of a website format with all the detail jsdoc provides and I really want to document the code inside my function nodes, not the outer workings, which is more of what I saw on other posts.
javascript is not json.
If you parse the json first, you will get javascript as a result.
However if you use so many function nodes, it somewhat defeats the purpose of node-red (low-code), you might be better off creating a project directly in nodejs instead (?)
There are many ways to document flows in node-red, including the function node.
One way: every node (and flow tabs) has a description tab.
PS: Node-red is more than just a low code development tool. I appreciate there is a sense of branding it that way to gain adoption, but it is capable of a lot.
You can certainly use JSDoc markup in your code, but I don't think there is a way to directly produce a document from it like you can with a traditional workflow.
However, I would say that it is probably best normally to keep function nodes fairly tight so JSDoc style in-line documentation would be minimally useful. I generally just use standard comments in function nodes but extensive JSDoc in my custom nodes for example.
If you find yourself needing really complex function nodes, I would encourage you to move that code out to a module and then reference that in the globals section of your settings.js.
Can you please elaborate on what you mean by "move that code out to a module"?
FYI, whether it be good practise of not, I do have complex code in my function nodes and I also have a complex relationship between nodes.
I really need something like jsdoc to create robust documentation. In-line comments etc, are just not helpful enough.
PS: I have been looking at a way to parse the JSON file to extract the JS out and save to a new file on which I can run jsdoc to create the documentation website. if you know a better way, please share.
Good old ChatGPT says:
"To parse this JSON file and extract the embedded JavaScript, you will need to use a JSON parser like JSON.parse() or JSON5.parse(). These parsers will read through the file and convert the JSON objects into a JavaScript object. You can then access the embedded JavaScript by looping through each object in the JavaScript object and extracting the values from the "func" property."
OMG, I just asked ChatGPT and it gave me the code and it worked....
Now I have to deal with the file containing duplicate variable names, as it's pulling in all flows and all function nodes (presumably) into one file...hmmm.
Haha, well you have immediately hit both the strength and the weakness of ChatGPT!
It looks right at first sight and then you realise it isn't.
I think I would probably have taken a more measured approach and found my most complex nodes first to get the biggest benefit. But whatever.
I'm not sure what level of Node.js knowledge you've got so apologies if I'm telling you what you already know.
At its most basic, node.js module is a file of javascript with an export statement that makes variables (including functions) available externally.
In another node.js app, you require the module. So in your settings.js globals section you might say myGloriousCode: require('./mymodule'),. Then in the function node, you can simply const myGloriousCode = global.get('myGloriousCode') and then use it as any other node.js library.
All you need in your module is at least one export statement - you already know how to do that because that's exactly what happens in the settings.js file Anything that you export in the module can be accessed in the function node. So if you need a specific function, lets say you want a function to add two numbers. You export the myAddyThing function from the module and use it as myGloriousCode.myAddyThing(1, 2) in the function. So all of the code in the function that currently does that adding up, you now move to the function in the module. The module, of course, can now be re-used in any function node.
You can also get just specific functions from the module as in: const {myAddyThing, myOtherThing} = global.get('myGloriousCode').
Anything that you export in the module can be accessed in the function node. So if you need a specific function, lets say you want a function to add two numbers. You export the 