For a Groovy or Java class or method, I would generally include any API-level documentation in a doc comment (aka Javadoc comment), rather than a regular comment. What is the analogous way of adding such comments about a Groovy script?
I personally don't care so much about whether the Javadoc tool picks up the documentation. However, documentation about the purpose of a Groovy script seems conceptually analogous to a doc comment on a class; therefore, I would intuitively expect them to be in a doc comment. If my intuition is wrong and doc tags are not the standard way of commenting the intent of a Groovy script, what is the preferred method to document the purpose of a script?
The syntax section of the Groovy language specification defines the elements that a Groovydoc comment can be associated with:
[Groovydoc] comments are associated with:
- type definitions (classes, interfaces, enums, annotations),
- fields and properties definitions
- methods definitions
Although the compiler will not complain about Groovydoc comments not being associated with the above language elements, you should prepend those constructs with the comment right before it.
A script has no class type definition to put the Groovydoc comment before.
There is an open issue requesting this functionality in the Groovy issue tracker at GROOVY-8877:
Groovydoc doesn't offer any direct way to document Groovy scripts. It will process comments on classes in a Groovy script, but not any sort of file-level or top-level comment.
In summary, script-level Groovydoc comments are not currently supported in a Groovy script file.