YAMLs can be complex. Thus then need to document them by adding comments. There are only two ways, of which I have knowledge, to add comments. One is to add alias: statements (I"ve not had much luck with this) and the other is a multi-line description.
description: >
opens family room blinds at sunrise eol
Add a line like this to open earlier: offset: "-00:28:00"
(note how I had to extend the first line so the information following can be on a second line)
The hashtag doesn’t work. Lines with hashtags are removed when the YAML is saved. It was explained to me that it would make the some other part of HA more difficult and possible slow down the automation/script.
This documenting of YAMLs is important so that other’s including one’s future self, can understand what the function should be (not necessarily is)
If Home Assistant truly wants to be a world class platform the hack and move-on attitude has to be abandoned.
Here’s what I mean by that: I have found incorrect, missing, and lacking documentation. If I post the information in this forum, I get, “At the bottom of the documentation page is a place where your can report this”.
In the case of Help us improve our documentation. I have done this several times and two years later the issue is closed because there is no activity on the page.
In the case of edit this page I am instructed to make a fork of the documentation page. I don’t not have the expertise to do make a fork.
Community Guides is a good idea, but I fail to see any organization.
Not following. I have a config/packages directory where my yaml files live and I update them there. In addition to .md file for describing the overall system, each of my yamls has a generous amount of comments using what I think you are calling hastags. Here’s an example:
###############################################################################
# LIGHTING -- INDOOR PACKAGE
###############################################################################
#
# PURPOSE:
# This package manages automated lighting control for indoor spaces including
# living room lamps, seasonal decorative lighting, and master bedroom lighting.
# Features occupancy-aware shutoff, sunset-based triggering, manual control
# overrides via helper toggles.
#
# AUTOMATIONS:
#
# 1. Living Room Lamps -- Fade Up Before Sunset (Scene 31)
# Gradually illuminates living room lamps 40 minutes before sunset
#
# 2. Living Room Lamps -- Night Off at 11:20 PM + Random Delay (Scene 2.....
I edit the files, use the developer tools checks and appropriate reloads to get them going. I’m sure my comments get stripped under the hood on their way to running automations, but that is invisible to me and comments always remain in my source file.
Solution: to comment a YAML use a multiline description or learn Packages
I consider myself a typical user. I access my automations/scripts by setting–>Automations & Scenes–>[click on automation to be edited]
I am presented with the visual editor (how does one add comments or modify description in the visual editor?) I click the upper vertical 3 dots then edit in YAML. Modify, save. comments are now gone.
@paulbates has a different method, Packages, an Advanced configuration of the Documentation. A typical user, such as myself, would not understand that bundl[ing] configurations from multiple integrations has anything to do with automations or scripts. After spending the last hour reading the Packages documentation, I still don’t know how it would benefit me. One benefit, though, described here in this thread but not in the Packages documentation, is to have persistent comments.
@Didgeridrew gives us a link to that I was unable to find in the Home Assistant Documentation though it is oft seen in the this forum. I appreciate the link and perhaps someone ending up here will be helped.
While a bare-bones version of that information is actually linked in the docs, you can’t expect HA’s docs to cover every detail about all of the underlying languages and technologies it uses… the docs are already overwhelmingly detailed and extensive for most “typical” users.
In case you’re curious where it’s linked in the docs…
The first section in the YAML syntax page has a link to the Style Guide in the Dev docs.
It’s too bad that the schema for every yaml block allowed, say, a “_comment” key or something like that.
Kind of hacky, but I have also used variables sections and add a “comment” key.
One tiny, minor problem with both description and alias is that those show up various places. I have a very long description in a script and when I run that I have to scroll way down to get to the fields. And the aliases show up in the UI editor, which is great for short comments, but less great for documenting.
Oh, and big vote for packages. Besides the comments you can group together all the helpers, templates, scripts and automations relating to one thing (e.g. heating, irrigation, security) in a single file.
True. But every comment should start with a short poem that reflects the true feeling of the following software block. In some cases a limerick can be sufficient.
