Wie man Taglibs (oder Closures im Allgemeinen) in Groovy/Grails dokumentiert

Question

Ich schreibe meine erste Taglib als Teil eines Plugins und ich möchte es dokumentieren. Javadoc hinzufügen (gibt es irgendeinen Platz, der groovydoc dokumentiert oder ist es wirklich das Gleiche?) Scheint nicht für Nicht-Methoden zu funktionieren.

Insbesondere wie die def mytag zu dokumentieren:

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

Wie viele Dinge in Grails sind Schließungen spezifiziert verwenden, wenn es wirklich nicht möglich ist, sie zu dokumentieren, dann sieht es aus wie wir ein Problem haben. Gibt es eine andere Lösung mit separaten Dokumentationsdateien, die ich verwenden sollte?

Answer 1

Ich habe gerade gelesen über die neue Groovy 1.6 RC, die mich zu Jira, die ein paar offene Bugs in Bezug auf Groovydoc, einschließlich einer speziell über die Dokumentation fields and properties, die noch offen ist. Der letzte Kommentar spricht von einer Teilimplementierung in trunk, also werde ich das überprüfen müssen.

Damit wird der aktuelle Status gelöscht. In der Zwischenzeit habe ich mich gezwungen, mein Taglib freizugeben und es auch zu dokumentieren, was ich mit einer normalen HTML-Seite (wiki-generated) gemacht habe. Dafür gibt es etwas zu sagen, denn ich würde mich eigentlich abschrecken lassen, wenn die Einzeldokumente mit Details zu einer Taglib in einer Menge selbstgenerierter Drecks vergraben wären.

Answer 2

Ihre Frage machte mich neugierig und ich sah mich um. Es scheint keinen guten Weg zu geben, dies zu tun.

Ich denke, der beste Weg, dies im Moment zu tun wäre, nur die verfügbaren Tags und ihre Argumente in einem Klassen-Level-Javadoc-Header zu dokumentieren. Zumindest werden sie in Ihrer endgültigen API-Spezifikation für die Nutzer angezeigt.

Ich bemerke, dass es da draußen einige Diskussionen über groovydoc gibt, aber ich kann nichts total Offizielles darüber finden, besonders in Bezug auf die Verwendung mit Grails. Ich konnte groovydoc an einer meiner grails 1.0.3 apps mit dem folgenden Code arbeiten, aber es hat keine der Dokumentkommentare zu meinen taglib closures übernommen, als ich sie hinzugefügt habe.

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

könnten Sie in der Lage sein groovydoc zu massieren, um es mit Taglibs zu arbeiten, wenn man mit ihr Durcheinander lang genug, oder es kann mit Grails 1.1 Beta funktionieren, wenn Sie die Zeit haben, es zu versuchen.