Как задокументировать теги (или замыкания в целом) в Groovy / Grails - PullRequest
Новая
       24

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

11 голосов
/ 21 января 2009

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

Ответы [ 2 ]

3 голосов
/ 23 января 2009

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

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

0 голосов
/ 22 января 2009

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

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

...