[#GROOVY-4041] TRIVIAL doco issues for classes URL and File - jira.codehaus.org

Details

Type: Improvement
Status: Closed
Priority: Trivial
Resolution: Fixed
Affects Version/s: 1.7.0
Fix Version/s: 1.7.1, 1.8-beta-1
Component/s: groovy-jdk
Labels:
None

Number of attachments :
0

Description

Just had the need to look at the Groovy-JDK doco for URL#withInputStream and File#withInputStream.

Both methods have a 'See' section that references "#withStream(InputStream,Closure)."

I don't think that this exists anymore? In any case it isn't rendered as a link (which it would be if it existed, I assume).

The doco for several other methods in File also have the same 'See' section.

Activity

Ascending order - Click to sort in descending order

Hide

Permalink

Paul King added a comment - 08/Feb/10 5:26 AM - edited

It's a bug in gdk doco generator. As an example, if you look at Javadoc doco here:

http://groovy.codehaus.org/api/org/codehaus/groovy/runtime/DefaultGroovyMethods.html#withInputStream(java.io.File, groovy.lang.Closure)

It points to the right place which does still exist, i.e. here:

http://groovy.codehaus.org/api/org/codehaus/groovy/runtime/DefaultGroovyMethods.html#withStream(java.io.InputStream, groovy.lang.Closure)

To make matters less clear, we specifically exclude DefaultGroovyMethods from the GroovyDoc - because such methods are available in the gdk doco! (A little embarrassing I guess)

I have been waiting for the Eclipse patch to the grammar which keeps more comment info in the grammar before working too much more on the doco tools in general but perhaps this one should be fixed with some more urgency. I am sure it won't be too hard as appropriate code is already working for the GroovyDoc case.

Show

Paul King added a comment - 08/Feb/10 5:26 AM - edited It's a bug in gdk doco generator. As an example, if you look at Javadoc doco here: http://groovy.codehaus.org/api/org/codehaus/groovy/runtime/DefaultGroovyMethods.html#withInputStream(java.io.File, groovy.lang.Closure) It points to the right place which does still exist, i.e. here: http://groovy.codehaus.org/api/org/codehaus/groovy/runtime/DefaultGroovyMethods.html#withStream(java.io.InputStream, groovy.lang.Closure) To make matters less clear, we specifically exclude DefaultGroovyMethods from the GroovyDoc - because such methods are available in the gdk doco! (A little embarrassing I guess) I have been waiting for the Eclipse patch to the grammar which keeps more comment info in the grammar before working too much more on the doco tools in general but perhaps this one should be fixed with some more urgency. I am sure it won't be too hard as appropriate code is already working for the GroovyDoc case.

Hide

Permalink

Paul King added a comment - 08/Feb/10 5:38 AM

In case the previous comment is too obscure, the gdk doco is generated from DefaultGroovyMethods (and related files).

A reference to "#withStream(InputStream,Closure)" is really a reference to "DefaultGroovyMethods#withStream(InputStream,Closure)" but after gdk munging "#withStream(InputStream,Closure)" should be turned into "InputStream#withStream(Closure)" within the gdk doco.

Any JavaDoc style reference not within the DefaultGroovyMethods files should remain unchanged (i.e. ones not starting with a # will be treated as normal references with the gapi/api). At the moment, # references are treated the same as external ones.

As a short-term hack, we could at least point them to the relevant api reference, e.g. #foo -> DGM#foo. This will look a little strange for anyone not familiar with the conventions relating the the DGM files but at least won't be broken.

Show

Paul King added a comment - 08/Feb/10 5:38 AM In case the previous comment is too obscure, the gdk doco is generated from DefaultGroovyMethods (and related files). A reference to "#withStream(InputStream,Closure)" is really a reference to "DefaultGroovyMethods#withStream(InputStream,Closure)" but after gdk munging "#withStream(InputStream,Closure)" should be turned into "InputStream#withStream(Closure)" within the gdk doco. Any JavaDoc style reference not within the DefaultGroovyMethods files should remain unchanged (i.e. ones not starting with a # will be treated as normal references with the gapi/api). At the moment, # references are treated the same as external ones. As a short-term hack, we could at least point them to the relevant api reference, e.g. #foo -> DGM#foo. This will look a little strange for anyone not familiar with the conventions relating the the DGM files but at least won't be broken.

Hide

Permalink

Paul King added a comment - 09/Feb/10 7:29 AM - edited

Fix applied to trunk. @see should be fixed so long as the fully qualified classname is in the @see comment and ditto for @link references.

If someone else can try it (run 'ant docGDK' and inspect generated HTML), that would be great. Otherwise I will push to 1.7 branch in a day or two.

Show

Paul King added a comment - 09/Feb/10 7:29 AM - edited Fix applied to trunk. @see should be fixed so long as the fully qualified classname is in the @see comment and ditto for @link references. If someone else can try it (run 'ant docGDK' and inspect generated HTML), that would be great. Otherwise I will push to 1.7 branch in a day or two.

groovy

TRIVIAL doco issues for classes URL and File

Details

Description

Activity

People

Dates