有没有一种方法可以在Groovy脚本中附加Javadoc文档注释？

Question

对于Groovy或Java类或方法，我通常会在文档注释（也称为Javadoc注释）中包含任何API级别的文档，而不是普通注释。那么在Groovy脚本中添加这样的注释有什么类似的方法吗？

个人而言，我不太关心Javadoc工具是否获取了文档。然而，关于Groovy脚本目的的文档似乎在概念上类似于类的文档注释；因此，我直觉地认为它们应该在文档注释中。如果我的直觉是错误的，文档标记不是注释Groovy脚本意图的标准方式，那么记录脚本目的的首选方法是什么？

- M. Justin

---

你想了解Groovydoc吗？这里有一个使用groovydoc在脚本中的例子。 - dmahapatro

@dmahapatro — 那个链接确实展示了我所问的内容。但是，它并不完全权威。此外，如果您查看类的GroovyDoc输出和示例中的脚本，您会发现类级别的文档在GroovyDoc类示例中输出，但在脚本示例中没有输出。这让我相信这可能并不是实际上的“正确”方法。 - M. Justin

文章本身指出，文档未包含在Groovydoc输出中：“生成的Groovy脚本文档仅记录了脚本中定义的方法”。 - M. Justin

Answer 1

Groovy 语言规范的 语法部分 定义了 Groovydoc 注释可以关联的元素：

[Groovydoc] 注释可与以下元素相关联：

• 类型定义（类、接口、枚举、注解）
• 字段和属性定义
• 方法定义

虽然编译器不会抱怨 Groovydoc 注释未与上述语言元素关联，但您应该在其前面加上注释。

脚本没有类类型定义来放置 Groovydoc 注释。

在 Groovy 问题跟踪器 GROOVY-8877 中有一个开放问题请求此功能：

Groovydoc 没有任何直接的方法来记录 Groovy 脚本。它将处理 Groovy 脚本中的类上的注释，但不会处理任何文件级别或顶级注释。

总之，目前不支持在 Groovy 脚本文件中使用脚本级别的 Groovydoc 注释。

- M. Justin

---

很遗憾，情况仍然如此。我可以为我的脚本中的函数生成文档，但在顶部没有描述脚本的内容。 - Levi