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

（注：这与“如何”或“如何”的问题不同）

当一段有文档记录的代码用注释修饰时，这 注释通常显示在生成的javadocs中（对于

@Documented

注释）。 但是如果我想给javadoc添加一些推理呢？（为什么需要注释 对于这段代码？）

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

/**
 * My piece of code.<p>
 * 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

标记处的注释与注释本身一起出现在生成的Javadoc中

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

---

有没有合适的方法做注释注释？还有其他javadoc标签可以帮助吗？

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

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

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

注释有许多用途，其中包括：

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

资料来源：

以JUnit、JavaEE或Spring为例，这些注释在教程和Java文档中都有描述

• @测试

  -

• @EJB

  -

• @Autowired

  -

在我看来是自描述性的，或者在各自的java文档中被阐明

注释是链接的，因此您可以在javadoc页面跳转到注释本身。我认为这应该足够了

---

我可以进一步建议，使用

@see for javadoc，因此是javadoc标记的特定顺序。
那么您要问的是如何在注释类上记录为什么应用注释？@chrylis是的，没错。通常注释是众所周知的，不需要解释。我想记录的是为什么选择了特定的注释。例如，当一个类用
@Singleton
注释时，每个人都知道它是做什么的，但是经常需要写下来的也是为什么这个类必须是
@Singleton
，到目前为止，我想不出更好的解决方案，那就是用javadoc本身编写它。您可以使用
将其格式化为为此目的保留的单独部分，例如，显然没有额外的原因标签：-（好的，是的。注释应该是，在我的例子中，JUnit
@Parameter
，在源代码中有文档记录。使用链接很容易访问，没有其他方式。