Cómo documentar taglibs (o cierres en general) en Groovy/Grails

Question

Escribo mi primer taglib como parte de un complemento y me gustaría documentarlo. Agregar javadoc (¿hay algún lugar que documente groovydoc o es realmente lo mismo?) No parece funcionar para los no métodos.

Específicamente, cómo documentar la mytag def en:

/** 
* 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" 
    } 
} 

Como muchas cosas en Grails se especifican mediante cierres, si en realidad no es posible documentar ellos, entonces parece que tenemos un problema. ¿Hay alguna otra solución que implique archivos de documentación separados que debería estar usando?

Answer 1

Acabo de leer sobre el nuevo Groovy 1.6 RC, que me llevó a Jira, que tiene un par de errores al abrir groovydoc, incluyendo uno específicamente sobre la documentación de fields and properties, que todavía está abierto. El último comentario habla de una implementación parcial en trunk, así que tendré que verificarlo.

De modo que aclare el estado actual. Mientras tanto, me obligué a liberar mi taglib en la naturaleza y también a documentarlo, lo cual hice usando una página HTML normal (generada por wiki). Hay algo que decir acerca de eso, porque en realidad sería desilusionado si los únicos documentos con detalles sobre un taglib fueran encontrados enterrados en un montón de restos autogenerados.

Answer 2

Tu pregunta me hizo sentir curiosidad y eché un vistazo. No parece que haya una buena forma de hacer esto.

Creo que la forma más óptima de hacerlo en este momento sería simplemente documentar las etiquetas disponibles y sus argumentos en un encabezado javadoc de nivel de clase. Al menos de esa manera aparecerán en tu especificación API final para que la gente vea.

Noté que hay un poco de discusión sobre groovydoc, pero parece que no puedo encontrar nada totalmente oficial al respecto, especialmente en términos de uso con Grails. Pude hacer que groovydoc trabajara en una de mis aplicaciones Grails 1.0.3 con el siguiente código, pero no recogí ninguno de los comentarios del documento en mis cierres taglib cuando los agregué.

<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> 

es posible que pueda dar masajes groovydoc a conseguir que funcione con taglibs si meterse con él el tiempo suficiente, o puede trabajar con Grails 1.1 beta si tienes el tiempo para probarlo.