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

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


grails groovy documentation
person Bart Schuller    schedule 21.01.2009    source источник

Ответы (2)


arrow_upward
3
arrow_downward

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

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

person Bart Schuller    schedule 22.01.2009

arrow_upward
0
arrow_downward

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

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

person Rob Hruska    schedule 22.01.2009