Dear all! Documenting our flows ist very important. Self documentation (like proper names, groups, etc.) is means, but not always sufficient. Additional information ('Description') added to flows helps here and there.
But we often need or would greatly benefit from seeing some information directly when looking at a flow. Comment node comes to the rescue. Unfortunately, it does not fully serve my needs.
I can give a name to a Comment node and add extra information as markdown. Great.
But getting that information requires serious moving, clicking to reaveal it and, again, to hide it. This interrupts my flow.
It was pointed out that one can add \n to the name to have more lines displayed. I call this abuse: I have to enter this in a small field to get what I want. I see this in flows here. This creatitivity tell us: There's a need.
It would be great if the authorities would consider to beef up the documentation features of NR. I see basically two possibilities building on the Comment node within the current structure:
Comment node is shown as now, information pops up when you hoover over it
Comment node information is shown instead of the name (this should be optional as a per node feature, default is 'off' to have downward compatibility)
Comment nodes can be tied to, connected to, attached to other nodes if they are within the same group, so no real hard pressure here (although the idea of attaching "notes" to entities on the panel has something, hasn't it?)
Good call, perhaps this is something that could be considered for v5?
In fact, taking this idea further, perhaps it should be a standard feature for all nodes? An option to expose a node's comment in the flow instead of the name?
I'm using NR v4.0.3 This version offers like a tooltip at the top left of a comment box to indicate there are comments inside. If you hover over it for a couple of seconds it will reveal what's inside.
I use NR 4.1.2 and I cannot reproduce this.
Yes, my comment node too gets a little symbol to let me know there is something.
But: Hovering does nothing (latest Firefox on macOS. pop ups allowed). I cannot reproduce the behavior you describe.
And: Even if it showed content after some time, some delay … This would be insuffucient.
I would like to see relevant information at a glance. I would like to have it right there under my eyes. No two step pop up, open close, but there.
And sometimes more info is required than a creativly formatted, trickily entered "name" of a node.
You can also make use of groups to wrap a bunch of nodes - and then add text to the title of that - admittedly it suffers in the same way as the title of comment nodes (IE has to be entered onto one line) - but may look better for your purposes - and of course being a group all the nodes contained move with the text...
I'm sure it's just a pull request away just need someone to code it.
(more seriously it would probably be quite tricky as sizing the group to fit and to fit text around nodes would have loads of weird edge cases to handle - also overloading of html tags within markdown is bound to also cause oddness. Not impossible but...)
I think a better idea would be some way to make it easier multiple lines in the name field of the comment node. Eg maybe a checkbox option to concatenate the body with the name
Oh oh, now you've got me thinking - always a dangerous thing!
Wouldn't it be fantastic for groups to have an option for a header and another for a footer with at least one of them allowing Markdown rendered to HTML?
Well, that would probably satisfy most needs. But where's the fun in that!
I've had a quick look in the node-red source, but I'm not familiar enough to find where nodes are visualised in the main code. Without that, I am not sure I can work out what would need to change to make a more flexible display.
I only just discovered you can do that - a \n surrounded by white space.
The group seems to expand to contain the multi-line name.
Could it be made to display the group description (which might be more than just text), or the name if there is no description?
Alternatively, can the "There is documentation" badge be shown before the name, clickable to get a popup?
This could be shown on a tab with description too?
That's a good point, the info panel does show the description for groups and tabs too.
The OP sounds a bit negative/demanding. But there are valid points here I think.
When I share a flow with people who might have to tinker with it, I have resorted in the past to including multiple comment nodes below each other, because I wasn’t aware I could use \n in the comment name. It looks much better in the workspace to use a multiline comment node. But cramming multiple lines in the name of the comment node is a hassle. The same goes for using a group title: nice to learn I can do this, but it’s a hassle.
The icon that indicates a comment node has content misses the mark for me, as clicking the icon will open the editor, showing the markdown code. I would instead expect it to open the Info panel in the sidebar, and maybe flash that panel to draw attention to it. Or draw a focus border around it? In the future Node-RED 5, with its split sidebars, showing/focusing the Info panel would not necessarily displace the debug panel and so it could be less disruptive to do this.
I’ve no clue how Dave gets that tooltip in his screenshot, or what comments he’s referring to. It looks useful to me though.
I could also imagine a checkbox in the comment node to ‘render description text inside the node‘, which would automatically render the description markdown in a multiline node. But this would be quite a big departure from the current design of Node-RED. In visual design it might be tricky, and it might entice users to use the editor itself as a dashboard.
yes - I agree - opening the editor seems odd - it would indeed (to my mind) be better to open the info panel (especially as in v5 we can now have split side panels). Or maybe enhance the edit panel to allow showing a preview mode (and jump to that).
I'm not sure comments/help counts as a dashboard... my long held aversion to making the editor a dashboard is about dynamic elements. If someone really wanted to fill their screen with instructions, or comments in order to make their flow more understandable - a bit like an architects plan or map with a key etc - then I've no problem with that. (OK I may have a slight OCD problem with it... but...)
It is about getting the flow documentation easily .
How easy do you want it ? What are you documenting that is so overly complex that you need it needs to be documented in such a way ?
The info panel exists specifically for this use case, that you think it is not 'easy' may be another problem.
The flow should describe itself, that is the core idea of node-red. The only thing I would like to see from the behaviour that is that the information shows up in the same panel as the help tab, instead of the info tab.
easy = directly available, visible without further work/effort.
After years of professional software development I have to say that "self documenting software" remains a myth. Software is so much more than code. It is decisions, patterns, algorithms, trade-offs , … worth to be kept visible in a proper documentation.
If all flows were self describing, we wouldn't need a "Comment node" at all. Since they are not and not all our flows will ever be self describing, we do need an easy to handle and useful "Comment node".
All I say ist the current Comment node has room for improvement wrt. "Usability".
Well yes, this could easily get out of hand.
I see one group in my flows has 50 lines of "Description" including details of API requirements and data structures.
Maybe better if the description was only shown as far as the first <hr> tag?
One of the elephants in the room is that all descriptions are entered in a markup (markdown?) editor but there is no practical way to show the formatted output. Dave says in this PR "We can't easily render markdown as SVG [below the group]" so even if it's useful, this PR isn't the full answer.
just need someone to code it.
