Как документация taglib (или закрытие в целом) в Groovy/Grails

Я пишу свой первый taglib как часть плагина, и я хотел бы его документировать. Добавление javadoc (есть ли место, где документы groovydoc или это действительно одно и то же?) Кажется, что не работает для не-методов.

В частности, как документировать def mytag в:

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

Я только что прочитал о новом Groovy 1.6 RC, который привел меня к Jira, у которого есть пара открытых ошибок в отношении groovydoc, в том числе и о документах поля и свойства, которые все еще открыты. В последнем комментарии говорится о частичной реализации в багажнике, поэтому я должен проверить это.

Таким образом, чтобы очистить текущий статус. В то же время я заставил себя выпустить свой taglib в дикую природу, а также документировать его, что я использовал с обычной HTML-страницей (созданной wiki). Есть что сказать об этом, потому что я действительно отложил бы, если бы единственные документы с подробностями в taglib были найдены похороненными в большом количестве автогенерированных dreck.

Ответ 2

Ваш вопрос вызвал у меня любопытство, и я осмотрел его. Не кажется, что есть хороший способ сделать это.

Я думаю, что наиболее оптимальным способом сделать это на данный момент было бы просто документировать доступные теги и их аргументы в заголовке 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, если у вас есть время попробовать.