A bit late for an answer, but for those who come to this thread with the same question: In automations and scripts you can use the top right menu to select Rename.
There you’ll find the description field. It can hold as much text as you like, and even supports markdown for formatting. So for instance the following description:
**This is a documentation test**
* Test 1
* Test 2
* *Test 3*
Looks fine to me
Shows this in the automation editor on top of the automation:
Also note that automations, scrips and scenes, even when built in the GUI, can just as easily be edited through VisualStudio Code, but the GUI may not keep the documentation you entered as yaml comments. So the description way is safer.