Question

我正在编写我的第一个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中的许多内容，如果真的无法记录它们，那么看起来我们遇到了问题。是否有其他解决方案涉及我应该使用的单独的文档文件？

Answer 1

我刚刚读到了新的Groovy 1.6 RC，它引导我使用了Jira，它有一些关于groovydoc的漏洞，其中一个特别关于记录fields and properties，它仍然是开放的。最新评论提到了主干的部分实现，所以我将不得不检查出来。

这样可以清除当前状态。与此同时，我强迫自己将我的taglib释放到野外，因此也记录了它，我使用常规HTML页面（wiki生成）进行了记录。有一些事情可以说，因为如果有关于taglib的详细信息的唯一文档被发现埋藏在大量自动生成的dreck中，我实际上会被推迟。

Answer 2

你的问题让我好奇，我做了一些环顾四周。似乎没有一种好方法可以做到这一点。

我认为目前执行此操作的最佳方法是在类级别的javadoc标头中记录可用的标记及其参数。至少在这种情况下，它们会出现在您最终的API规范中供人们查看。

我注意到有一些关于groovydoc的讨论，但我似乎无法找到任何完全正式的关于它，特别是在使用Grails方面。我能够使用以下代码在我的grails 1.0.3应用程序上运行groovydoc，但是当我添加它时，它没有在我的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让它与taglib一起使用，或者如果你有时间尝试它，它可能适用于Grails 1.1 beta。

如何在Groovy / Grails中记录taglib（或一般的闭包）

2 个答案: