有没有办法将 Javadoc 文档注释附加到 Groovy 脚本？

Question

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

我个人不太关心 Javadoc 工具是否获取文档。然而，有关 Groovy 脚本用途的文档在概念上似乎类似于类的文档注释；因此，我直觉地希望它们出现在文档评论中。如果我的直觉是错误的并且文档标签不是注释 Groovy 脚本意图的标准方式，那么记录脚本用途的首选方法是什么？

Answer 1

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

[Groovydoc] 评论与以下内容相关：

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

尽管编译器不会抱怨 Groovydoc 注释未与上述语言元素关联，但您应该在这些构造前面添加注释。

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

Groovy 问题跟踪器GROOVY-8877中有一个请求此功能的未决问题：

Groovydoc 不提供任何直接的方法来记录 Groovy 脚本。它将处理 Groovy 脚本中类的注释，但不处理任何类型的文件级或顶级注释。

总之，Groovy 脚本文件当前不支持脚本级 Groovydoc 注释。