Smart homes require a lot of contextual installation-specific information to understand. I can add a markdown card to a dashboard, but often I find the place where additional documentation is actually needed is when I dig into a specific entity, device, integration, automation, helper, etc for maintenance. Being able to add a few lines of notes to each of these would go a long way to making my setup more maintainable by both future me and by my family members, increasing HAF.
A significant issue is you CAN add # in-line comments to YAML via a text editor BUT if you ever touch the graphical automation editor, it deletes # comments and reformats code even re-ordering attributes.
My guess is the otherwise wonderful GUI automations editor round-trips automations YAML => internal JSON => YAML or similar and the parsers strip the text (like CPP would).
Given the horrors seen round-tripping files through MS Word, LibreOffice, etc, I don’t see preserving comments in YAML being easy.
Perhaps alias: 'Text' and description: 'More text' is all we can get?
1 Like
I only break into YAML when what I’m doing is absolutely not possible through the GUI. My other household members would rather set fire to the house and move than open a yaml file, so any documentation placed there would not be particularly useful in my house.
This would be huge for me. For instance, I just added a trigger to an automation for 9pm, I only want it to run that trigger when I’m not home, otherwise I have a different trigger that goes at bedtime. I have to go down to the actions and see the condition I’ve set for that particular trigger. I would use this with every automation and script.
Adding comments to helpers and dashboard elements would also put me over the moon. It would be just fantastic… to know what this timer is for…
Please allow comments in automations.
Ideally this will be enabled through the visual editor, but it would be nearly as good if they were only accepted on the text editor.
Why? I often have the need to record comments about why I’ve chosen a particular logic or name - and sometimes want to reference URLs etc. Being able to do this in the automation would be so helpful!
+1 to this, why cant # in yaml be used for comments? It pretty common and industry standard
Alias is a text field you can use as comment.
In GUI click on the three dots on the trigger/condition/action and rename
There’s a WTH for that: WTH can’t I add contextual documentation?
And a WTH for that: WTH comments disappear from yaml editor?
There have been multiple long-winded discussions on this topic as well; the explanation is that while YAML does support comments, the translation from YAML to JSON doesn’t, which is why comments are not possible in the UI at this time.
Thank you, this is a useful workaround and I will try it.
You could easily generate a comment field any time a # is detected in conversion from yaml to json and re render it when viewing yaml. The works already there to render to and from yaml and json