[GROOVY-8877] No way to add a top-level Groovydoc comment a Groovy script

• Type: Bug
• Status: Open
• Priority: Minor
• Resolution: Unresolved
• Affects Version/s: 2.4.8
• Component/s: GroovyDoc
• Environment: $ groovy --version ; Groovy Version: 2.4.8 JVM: 1.8.0_181 Vendor: Oracle Corporation OS: Linux
• Assignee: Unassigned
• Reporter: Craig Ringer
• Created: 13/Nov/18 03:30
• Updated: 02/Sep/20 20:20

Description

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. For example, a demo.groovy:

#!groovy

/**
 * Groovydoc comment on this script.
 *
 * This script does nothing. It's really very unexciting.
 */

println "I do nothing, nothing!"

/** Documented method */
def docmethod(){}

/** Documented class */
class Documented {}

when processed with

mkdir doc
groovydoc -d doc/ -private demo.groovy

produces a doc/DefaultPackage/demo.html that contains

docmethod()
Documented method

and it produces a doc/DefaultPackage/Documented.html for the class.

But the top doc-comment is totally ignored:

$ grep -r 'This script does nothing' doc/
$

Also there's no link from demo.html to Documented.html or vice versa. Which there should be so that the docs show which scripts define which class(es).