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

["Craig Ringer (JIRA)" <ji...@apache.org>]

Craig Ringer created GROOVY-8877:
------------------------------------

             Summary: 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


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)