如何使用 javadoc 正确记录注释？

Question

（注意：这与where to put the annotation 或如何document the annotation itself 的问题不同）

当一段记录的代码用注释修饰时，这 注释通常出现在生成的 javadocs 中（对于 @Documented 注释）。 但是如果我想在 javadoc 中添加一些推理呢？ （为什么需要注释 这段代码？）

我想到了两种方法，但都不理想。

/**
 * My piece of code.<p>
 * Why @MyAnnotation is needed
 */
@MyAnnotation
public void pieceOfCode() {

这样原因会出现在生成的javadoc中，而不是和注解本身一起出现。

/**
 * My piece of code.
 */
// Why @MyAnnotation is needed
@MyAnnotation
public void pieceOfCode() {

就像这个原因与注解本身非常接近（在重构中迷失的机会更少）， 但不会出现在生成的 javadocs 中。

我想要的是 @param javadoc 标签之类的注释，例如@ann:

/**
 * My piece of code.
 * @ann MyAnnotation  There's a reason
 */
@MyAnnotation
public void pieceOfCode() {

对于@Documented 注释，我希望@ann 标记处的注释与注释本身的提及一起出现在生成的javadocs 中。

有没有正确的方法做评论注释？还有其他 javadoc 标签可以提供帮助吗？

Answer 1

我认为注释本身应该是自我描述的并且作为元数据是显而易见的，所以应该只有很少的文档本身。

注释是一种元数据形式，提供有关程序的数据，该程序是 不是程序本身的一部分。注释没有直接影响 他们注释的代码的操作。

注解有多种用途，其中：

• 编译器信息 - 编译器可以使用注释 检测错误或抑制警告。
• 编译时和 部署时处理——软件工具可以处理注释 生成代码、XML 文件等的信息。
• 运行时处理 - 一些注释可在运行时检查。

来源：http://docs.oracle.com/javase/tutorial/java/annotations/

如果您以 JUnit、Java EE 或 Spring 为例，注释会在教程和 java 文档本身中描述。

• @Test - http://junit.sourceforge.net/javadoc/org/junit/Test.html
• @EJB - http://docs.oracle.com/javaee/6/api/javax/ejb/EJB.html
• @Autowired - http://docs.spring.io/spring/docs/2.5.6/api/org/springframework/beans/factory/annotation/Autowired.html

在我的意义上是自我描述的，或者在各自的 java 文档中得到澄清。

注解已链接，因此您可以在 javadoc 页面中跳转到注解本身。在我看来，这应该足够了。

我可以进一步建议，使用@see <annotation> 来表示额外的含义。我认为@param 没有类似的东西。到目前为止，我一直在查看 http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#orderoftags 的 javadoc，因此这是 javadoc 标记的特定顺序。