Я пишу свой первый taglib как часть плагина, и я хотел бы его задокументировать. Добавление javadoc (есть ли место, где документируется groovydoc или это действительно одно и то же?) Похоже, не работает для не-методов.
В частности, как задокументировать тег def в:
/**
* 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"
}
}
Поскольку многие вещи в Grails задаются с помощью замыканий, если их действительно невозможно задокументировать, то, похоже, у нас есть проблема. Есть ли какое-то другое решение, включающее отдельные файлы документации, которые мне следует использовать?
Ответ 1 · рейтинг 3 · Bart Schuller
Я только что прочитал о новом Groovy 1.6 RC, который привел меня к Jira, в которой есть пара открытых ошибок, связанных с groovydoc, в том числе одна конкретно о документировании поля и свойства, который все еще открыт. В последнем комментарии говорится о частичной реализации в транке, поэтому мне нужно это проверить.
Так что это проясняет текущий статус. Тем временем я заставил себя выпустить свою taglib на волю, а также задокументировать ее, что я и сделал, используя обычную HTML-страницу (сгенерированную вики). Есть что сказать по этому поводу, потому что меня бы на самом деле оттолкнуло, если бы единственные документы с подробностями о taglib были найдены похороненными во множестве автоматически сгенерированного мусора.
Ответ 2 · Rob Hruska
Ваш вопрос вызвал у меня любопытство, и я немного осмотрелся. Не похоже, что есть хороший способ сделать это.
Я думаю, что наиболее оптимальным способом сделать это на данный момент было бы просто документировать доступные теги и их аргументы в заголовке javadoc на уровне класса. По крайней мере, таким образом они появятся в вашей окончательной спецификации API, чтобы люди могли их увидеть.
Я заметил, что есть некоторые обсуждения о groovydoc, но я не могу найти ничего абсолютно официального о нем, особенно с точки зрения использования с Grails. Мне удалось заставить groovydoc работать с одним из моих приложений Grails 1.0.3 с помощью следующего кода, но он не улавливал комментарии к документам в моих замыканиях taglib, когда я их добавлял.
<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>
Возможно, вы сможете помассировать groovydoc, чтобы заставить его работать с taglibs, если вы возитесь с ним достаточно долго, или он может работать с бета-версией Grails 1.1, если у вас есть время попробовать.
