Documenting taglibs (or closures in general) in Groovy/Grails

Question

I am writing my first taglib as part of a plugin and I would like to document it. Adding javadoc (is there any place that documents groovydoc or is it really the same thing?) doesn't seem to work for non-methods.

Specifically, is it possible to document the def mytag in:

/**
 * This doc shows up
 */
class MyTagLib {
  static namespace = "myns"

  /**
   * This doc does not show up, but I'd like to document attrs.
   */
  def mytag = {attrs ->
    out << "something"
  }
}

As lots of things in grails are specified using closures, if it's really not possible to document them, then it looks like we have a problem. Or is there some other best practice involving separate documentation files that I should be using?

I'd appreciate any answers, pointers or insights.

Answer 1

Your question made me curious and I did some looking around. It doesn't seem that there's a good way to do this.

I'm thinking the most optimal way to do this at the moment would be to just document the available tags and their arguments in a class-level javadoc header. At least that way they'll appear in your final API spec for people to see.

I notice that there's some discussion out there about groovydoc, but I can't seem to find anything totally official about it, especially in terms of use with Grails. I was able to get groovydoc working on one of my grails 1.0.3 apps with the following code, but it didn't pick up any of the document comments on my taglib closures when I added them.

<property environment="env"/>
<target name="groovydoc">
  <taskdef name="groovydoc" classname="org.codehaus.groovy.ant.Groovydoc">
    <classpath>
      <path path="${env.GRAILS_HOME}/lib/groovy-all-1.5.6.jar"/>
    </classpath>
  </taskdef>
  <mkdir dir="docs/gapi"/>
  <groovydoc destdir="docs/gapi" sourcepath="grails-app" use="true" windowtitle="groovydoc" private="true"/>
</target>

You might be able to massage groovydoc to get it to work with taglibs if you mess with it long enough, or it may work with Grails 1.1 beta if you've got the time to try it.

Answer 2

I just read about the new Groovy 1.6 RC, which lead me to Jira, which has a couple of open bugs concerning groovydoc, including one specifically about documenting fields and properties, which is still open. The latest comment speaks of a partial implementation in trunk, so I will have to check that out.

So that clears up the current status. In the mean time, I forced myself to release my taglib into the wild and so also to document it, which I did using a regular HTML page (wiki-generated). There is something to be said for that, because I'd actually be put off if the sole docs with details on a taglib were to be found buried in lots of auto-generated dreck.