[
https://issues.apache.org/jira/browse/GROOVY-8877?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16684677#comment-16684677
]
Craig Ringer commented on GROOVY-8877:
--------------------------------------
The workaround I've adopted in my scripts is to define a dummy method. You
can't seem to groovydoc members other than methods. So I:
{{code:groovy}}
/**
* This is a comment on the script
*
* @see SomeOtherScript
*/
def doc(){}
... script body here ...
{{code}}
> No way to add a top-level Groovydoc comment a Groovy script
> -----------------------------------------------------------
>
> Key: GROOVY-8877
> URL: https://issues.apache.org/jira/browse/GROOVY-8877
> Project: Groovy
> Issue Type: Bug
> Components: GroovyDoc
> Affects Versions: 2.4.8
> Environment: $ groovy --version
> Groovy Version: 2.4.8 JVM: 1.8.0_181 Vendor: Oracle Corporation OS: Linux
> Reporter: Craig Ringer
> Priority: Minor
>
> 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}}:
> {code: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 {}
> {code}
> when processed with
> {code:sh}
> mkdir doc
> groovydoc -d doc/ -private demo.groovy
> {code}
> produces a {{doc/DefaultPackage/demo.html}} that contains
> {noformat}
> docmethod()
> Documented method
> {noformat}
> and it produces a {{doc/DefaultPackage/Documented.html}} for the class.
> But the top doc-comment is totally ignored:
> {code:sh}
> $ grep -r 'This script does nothing' doc/
> $
> {code}
> 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).
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
