有没有一种方法可以将Javadoc文档注释附加到Groovy脚本? [英] Is there a way to attach a Javadoc doc comment to a Groovy script?

问题描述

对于Groovy或Java类或方法，我通常会在doc注释(aka Javadoc注释)而不是常规注释中包含任何API级别的文档.添加有关Groovy脚本的注释的类似方法是什么?

For a Groovy or Java class or method, I would generally include any API-level documentation in a doc comment (aka Javadoc comment), rather than a regular comment. What is the analogous way of adding such comments about a Groovy script?

我个人不太在乎Javadoc工具是否可以提取文档.但是，有关Groovy脚本目的的文档在概念上似乎类似于对类的文档注释.因此，我直觉上希望他们在文档注释中.如果我的直觉是错误的，并且doc标签不是注释Groovy脚本意图的标准方法，那么 是记录脚本用途的首选方法是什么?

I personally don't care so much about whether the Javadoc tool picks up the documentation. However, documentation about the purpose of a Groovy script seems conceptually analogous to a doc comment on a class; therefore, I would intuitively expect them to be in a doc comment. If my intuition is wrong and doc tags are not the standard way of commenting the intent of a Groovy script, what is the preferred method to document the purpose of a script?

推荐答案

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

The syntax section of the Groovy language specification defines the elements that a Groovydoc comment can be associated with:

[Groovydoc]注释与:

[Groovydoc] comments are associated with:

• 类型定义(类，接口，枚举，注释)
• 字段和属性定义
• 方法定义

尽管编译器不会抱怨Groovydoc注释与上述语言元素没有关联，但是您应该在这些结构之前添加注释.

Although the compiler will not complain about Groovydoc comments not being associated with the above language elements, you should prepend those constructs with the comment right before it.

脚本没有类类型定义，因此不能将Groovydoc注释放在前面.

A script has no class type definition to put the Groovydoc comment before.

在 GROOVY-8877的Groovy问题跟踪器中，有一个未决问题要求该功能. :

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

Groovydoc doesn't offer any direct way to document Groovy scripts. It will process comments on classes in a Groovy script, but not any sort of file-level or top-level comment.

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

In summary, script-level Groovydoc comments are not currently supported in a Groovy script file.

这篇关于有没有一种方法可以将Javadoc文档注释附加到Groovy脚本?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！