5

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?

M. Justin
  • 14,487
  • 7
  • 91
  • 130
  • [Groovydoc](http://docs.groovy-lang.org/latest/html/documentation/#_groovydoc_the_groovy_java_documentation_generator) is what you are after? Here is example of using [groovydoc in scripts](http://www.javaworld.com/article/2074120/core-java/documenting-groovy-with-groovydoc.html). – dmahapatro Nov 05 '15 at 23:10
  • 1
    @dmahapatro — That link does demonstrate exactly what I was asking. However, it's not exactly authoritative. Furthermore, if you look at the GroovyDoc output for a class vs. the script in the example, you'll see that the class-level docs are output in the GroovyDoc class examples, but not in the script examples. This leads me to believe that this may not actually be the "correct" way of doing this. – M. Justin Nov 06 '15 at 21:30
  • The article itself points out that the docs aren't included in the Groovydoc output: "the generated documentation for the Groovy script only documented the methods defined in the script" – M. Justin Sep 02 '20 at 20:16

1 Answers1

5

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.

M. Justin
  • 14,487
  • 7
  • 91
  • 130
  • 3
    This sadly is still the case. I can generate docs for the functions in my script, but nothing at the top to describe the script. – Levi Aug 27 '20 at 09:15