如何使用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() {

就像那样，原因非常接近注释本身（在重构中丢失的机会较少）， 但不会出现在生成的javadoc中。

我想要的是注释的@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标记的特定顺序。