In a sign of its continuing maturity, the Groovy project's next release, set for the next couple of weeks, will include support for Groovydoc. What is Groovydoc? How does it relate to javadoc? And what's the point? Here, in an interview with Jeremy Rayner, Groovophile from the earliest hour, we learn all about it.

Jeremy, who are you and what do you do in the Groovy project?

Hi, I'm a software engineer for a data services company in the City of London by day, and by night I develop open source for fun. I also run the London Java Meetups, which is a (usually) monthly social event for Java developers in the city from all sectors.

I'm very quiet, I don't have time to be on the mailing lists like my excellent colleagues, but I have a passion for Groovy. (I don't think many people knew who I was at Grails eXchange this year.) I've been involved in Groovy since I met James Strachan in 2003, he was hacking away on a new language in the corner of a darkened room. The language really peaked my interest, as a long time Java developer, as it was written by Java developers, for Java developers, to give good syntactic sugar for often used programming tasks on the JVM.

I've been a core committer on the project since 2004, and helped setup the very first Groovy Developers Conference that year.

I wrote the current parser for Groovy, along with a very detailed test suite that provides some engineering rigour to the language, ensuring that we know which language constructs are being used, and which bits of cruft (from growing the language) are unused.

I don't like the parser trait of including 'action' code during the parse, so I created a solid visitor pattern over the homogeneous source AST that Antlr outputs. I've applied this to a number of cool uses so far, including the ability to print out source code from a supplied AST, outputting the AST as a mindmap for ease of visualization, conversion of java sources to groovy sources at the source AST level (java2groovy).

Here's some further info:

• http://video.google.com/videoplay?docid=-7209282334029676664

• http://groovy.javanicus.com/ggug2/

I've also been involved in most other parts of the core of Groovy at some point over the last four years. Such things as the groovy ant task, the groovy reference card, work on the format, layout and content for the Groovy Language Specification, the framework for the current TCK, many things in the GDK, including the wonderful obj.with{...} method... The groovy build, the distribution bundle, the ?. operator, groovy emacs mode, the original groovy plugin for intellij, GSQL etc... Oh and one of my favourites, the 'listen' mode for groovy, like netcat, which executes the supplied script when someone connects on the listened port.

I also started http://searchgroovy.org/ and http://groovyuserguide.org and have tried, in a quiet English manner, to evangelise Groovy around the world. - Groovy at the Google offices in London - http://blip.tv/file/240976

And in my spare time I wrote:

• a wiki that allows groovy in the wiki sources http://groovy.javanicus.com/biscuit/
• a shell that allows you to ssh into your JVM and navigate around the object tree as if it were a file system. http://groovy.javanicus.com/grash/
• a regular expression mini IDE called the Groovy Regex Coach http://common-lisp.net/pipermail/regex-coach/2007-April/000178.html

Since GroovyDevCon 3 I have been looking into creating a javadoc-like tool, unimaginatively titled "Groovydoc".

"Unimaginative"? How about "Great!" instead? Can you explain exactly what exactly it is and what will it do for me?

Groovydoc is similar to Javadoc, in fact I treated Javadoc like a black box, you feed in your sources, and you get out the HTML frames which we are all so familiar with. I threw away the stuff in the middle and using the YAGNI (you ain't gonna need it) approach, I developed a replacement black box that could be fed both Java sources and sources from other dynamic languages like Groovy and produce output using velocity-like templating. Groovydoc output is very close to Javadoc output.

But Groovy is a scripting language, why would I be interested in generating something similar to Javadoc?

Well Groovy is just an implementation detail of your Java APIs, as far as the user is concerned. When they add your JAR to their classpath and attach the javadoc, they don't care what JVM language you implemented this in, and in Groovy we want to encourage that kind of interface level design.

Groovydoc provides rigour to your codebase, and takes the dynamic language out of toyland and into the Enterprise. Would you use an API that didn't have any Javadoc?

So this means there'll be Groovydoc for Groovy itself, as well as for the user's own applications, right?

Yes, it's available right now at http://groovy.codehaus.org/gapi/

Can you give some sample code for how a user might be able to generate Groovydoc?

It is available in groovy-1.1-rc1 right in the core of groovy, just call it from ant like this:

<taskdef name="Groovydoc" classname="org.codehaus.groovy.ant.Groovydoc">
   <classpath>
      <path path="${mainClassesDirectory}"/>
      <path refid="compilePath"/>
   </classpath>
</taskdef>

<Groovydoc 
      destdir="${docsDirectory}/gapi"
      sourcepath="${mainSourceDirectory}" 
      packagenames="**.*" use="true"
      windowtitle="Groovydoc" private="false"/>

How are you able to do this? What approach underlies this?

Well, as I wrote the parser and AST visitor/traversal algorithms, I was able to leverage these to read in any groovy source code. The visitor then constructs what I term the Groovy Doclet API, which is basically a one-for-one copy of the Java Doclet API, a tree structure which is broken down much the same way as you see in javadoc: packages/classes/members.

As I wrote a java2groovy program too, this works by parsing in the java sources using Michael Studmans java grammar (which I used as the basis of the current groovy grammar), so all I did was parse the java sources into a java AST, apply a 'Groovifier' turning it into a groovy AST ready for adding to the Groovy Doclet API tree.

Once the tree is assembled I then wrote a little harness for applying velocity-like templates (actually groovy templates) at three levels, the root, the packages and the classes. This was enough to recreate the structure needed for the existing html output of javadoc. You can plug in your own templates, and you're not limited to outputting html, I already have in the test suite xml output from this tool, which enables some external tools to query the API.

It got to it's current status in about June 2007. What makes it newsworthy right now is that with the release of 1.1 final just a week or two around the corner, it will be available for the average user who doesn't take the nightly snapshots. It works fine today for most uses in groovy-1.1.

What are the open issues?

• Class resolution - i.e. the hyperlinks between classes
• The devil is in the detail with javadoc, so many minor variations of member visibility, fields, declarations, all sorts of things, easier to see the side by side differences:

  • javadoc: http://groovy.codehaus.org/api/groovy/util/XmlNodePrinter.html vs

  • Groovydoc: http://groovy.codehaus.org/gapi/groovy/util/XmlNodePrinter.html

• other language support, if it compiles down to JVM bytecode I'm interested in making this a documentation system for other languages too. (e.g. fortress, jruby etc)

What's the timeline? When will it be ready for general use?

That's a tricky one, I'm not a big corporation, I'm just a little fella who writes this stuff on his train journey to and from work each day. I'd like to take this opportunity to ask your beloved readers, if they are interested, to come and help me put some meat on this skeleton that I've built.

When it is working exactly as you would like it to, what will the Groovydoc tool do for me?

Groovydoc will provide an exact replica of what Javadoc did, so you can use this tool as a drop-in replacement for your old model. It will also provide the ability to see dynamically added properties and behaviours for your classes, etc. It will allow you the freedom to implement your own JAR files for distribution, safe in the knowledge that you can provide decent API documentation, and they maybe need never know that you implemented the JAR in Groovy.