groovy

Integrate all Groovy API documentation

Details

  • Type: Improvement Improvement
  • Status: Open Open
  • Priority: Major Major
  • Resolution: Unresolved
  • Affects Version/s: None
  • Fix Version/s: None
  • Component/s: groovy-jdk
  • Labels:
    None
  • Number of attachments :
    0

Description

I currently have three links for Groovy-related API documentation: the JDK, the Groovy JDK, and the Groovy API docs. This makes it hard for users that are new to Groovy since they have to look in 3 different locations for docs.

All three should be integrated together as the Groovy API documentation, with individual entries indicating whether they are part of core Java, methods or properties added to those classes, or Groovy-only classes. This is probably non-trivial but worth the investment in effort.

One difficulty of course is knowing which Java API docs to integrate with the Groovy docs, but I would recommend whatever is the latest publicly available Java release.

Activity

Ascending order - Click to sort in descending order
Hide
Permalink
Phil DeJarnett added a comment -

I would love to see this.

(I thought this had been tried in the past, but the discussion then was that there may be legal issues redistributing the JDK docs. I looked, but couldn't find anything about this.)

Show
Phil DeJarnett added a comment - I would love to see this. (I thought this had been tried in the past, but the discussion then was that there may be legal issues redistributing the JDK docs. I looked, but couldn't find anything about this.)
Hide
Permalink
Cedric Champeau added a comment -

One of the problems of a unified API documentation is that Groovy isn't bound to a particular JDK. It may run on 1.5, 1.6 or 1.7, so you would need (at least) 3 distinct bundles.

Show
Cedric Champeau added a comment - One of the problems of a unified API documentation is that Groovy isn't bound to a particular JDK. It may run on 1.5, 1.6 or 1.7, so you would need (at least) 3 distinct bundles.
Hide
Permalink
Peter Ledbrook added a comment -

Phil: Interesting point. It wouldn't surprise me if there were such problems. Something to bear in mind. It might be easier to link through to the JDK API docs anyway, although doing so in a way that makes everything still feel integrated will be tricky.

Cédric: I thought about this and decided using the latest (recommended) for a particular Groovy version would be fine. The JDK is pretty good at indicating which classes, methods and fields are available in which Java versions. And anyway, the Groovy JDK docs already link through to a particular JDK. It's just tracking down the link for the class you want could be easier.

Show
Peter Ledbrook added a comment - Phil: Interesting point. It wouldn't surprise me if there were such problems. Something to bear in mind. It might be easier to link through to the JDK API docs anyway, although doing so in a way that makes everything still feel integrated will be tricky. Cédric: I thought about this and decided using the latest (recommended) for a particular Groovy version would be fine. The JDK is pretty good at indicating which classes, methods and fields are available in which Java versions. And anyway, the Groovy JDK docs already link through to a particular JDK. It's just tracking down the link for the class you want could be easier.
Hide
Permalink
Graeme Rocher added a comment -

Agree 100% the current separation is a big PITA

Show
Graeme Rocher added a comment - Agree 100% the current separation is a big PITA
Hide
Permalink
Phil DeJarnett added a comment -

Would there be any way to merge the documentation after-the-fact? In other words, create a script that allows the end user to download both the Grails & Java docs, then merge them into one unified set. (Or download the Java docs, then insert the grails docs directly.)

This would avoid the legal issues of redistributing the docs, while still allowing the docs to be complete. It would also allow for different versions of the Java docs to be selected by the end user.

Show
Phil DeJarnett added a comment - Would there be any way to merge the documentation after-the-fact? In other words, create a script that allows the end user to download both the Grails & Java docs, then merge them into one unified set. (Or download the Java docs, then insert the grails docs directly.) This would avoid the legal issues of redistributing the docs, while still allowing the docs to be complete. It would also allow for different versions of the Java docs to be selected by the end user.
Hide
Permalink
Peter Ledbrook added a comment -

Possibly, but I can't imagine many users wanting to do that. I think a first step would be to integrate Groovy JDK and Groovy API docs and provide links through to the JDK docs. We could be put links to the java.* classes in the left bar and link those straight through to the JDK pages, except for classes that Groovy extends. Those pages should have prominent links through to the corresponding class in the JDK docs.

Show
Peter Ledbrook added a comment - Possibly, but I can't imagine many users wanting to do that. I think a first step would be to integrate Groovy JDK and Groovy API docs and provide links through to the JDK docs. We could be put links to the java.* classes in the left bar and link those straight through to the JDK pages, except for classes that Groovy extends. Those pages should have prominent links through to the corresponding class in the JDK docs.

People

  • Assignee:
    Unassigned
    Reporter:
    Peter Ledbrook
Vote (11)
Watch (7)

Dates

  • Created:
    Updated: