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

groovy & grails

Question

Estoy escribiendo 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 el def mytag 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 de las cosas en Grails se especifican utilizando cierres, si realmente no es posible documentarlas, 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 abiertos relacionados con groovydoc, incluido uno específicamente sobre la documentación de campos y propiedades , que aún está abierto. El último comentario habla de una implementación parcial en trunk, así que tendré que verificarlo.

Entonces eso borra 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 alrededor. No parece que haya una buena forma de hacer esto.

Estoy pensando 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 darle un masaje a groovydoc para que funcione con taglibs si se mete con el tiempo suficiente, o puede funcionar con Grails 1.1 beta si tiene tiempo para probarlo.