Monday, February 21, 2011

Groovy Javadoc-based API Documentation: Three's Company

I have found three sets of Javadoc-based API documentation to be worth bookmarking. In this post, I briefly look at each of these.


Groovy JDK API Specification (GDK)

The Groovy JDK API Specification (http://groovy.codehaus.org/groovy-jdk/) provides documentation for Groovy's GDK, a set of classes and interfaces that extend the same-named Java classes and interfaces. The overall description provided by this documentation is the simple sentence: "This document describes the methods added to the JDK to make it more groovy." Much of the Groovy goodness I use everyday comes from these handy extensions to Java SDK classes such as String, File, List, Object[], and Object.


Groovy Javadoc for Java Classes

Groovy's JavaDoc for Java classes (http://groovy.codehaus.org/api/) provides API documentation for Java classes used as part of the Groovy implementation. Examples of classes that are documented as Java classes in Groovy include AntBuilder, MarkupBuilder, Closure, Expando,
Sql, Tuple, XmlParser, XmlSlurper, and GString. I don't use this API documentation very often because it is limited to Groovy's Java classes and the next discussed API documentation covers both the Java and Groovy classes that are a standard part of Groovy in a single set of documentation.


GroovyDoc for Groovy and Java Classes

Groovydoc for Groovy and Java Classes (http://groovy.codehaus.org/gapi/) is one-stop shopping for both the Groovy and the Java classes delivered with Groovy that are not accounted for in the GDK documentation previously discussed. In other words, "Groovydoc for Java and Groovy Classes" covers the same Java classes covered by the last API documentation and throws the Groovy classes in as well. The GDK classes are not included and still must be accessed in the Groovy JDK documentation discussed first in this post. Because "Groovydoc for Groovy and Java Classes" contains the Java classes, it provides documentation for classes such as AntBuilder, Closure, XmlParser, XmlSlurper, and GString just as the last discussed documentation did. However, it also has Groovy classes and so includes the documentation for classes such as CliBuilder. The GroovyDoc documentation also states whether each document class is Groovy or Java. Because it does not include the GDK classes, it does not document Groovy's extensions to String, List, Object, and so forth.


Conclusion

There is no shortage of Groovy API documentation. The two sets most Groovy developers will need are for the Groovy GDK and for the GroovyDoc with Groovy and Java Classes.

No comments: