Java - 如何在方法注解中使用javadoc注释？

Question

我有以下方法：

   @Override
   public boolean myMethod()
   {
      // do stuff
   }

如果我想为这个方法添加Javadoc，是否有任何约定来同时使用@Override注释（或其他任何注释）？

我提出这个问题的原因是因为我读到过Javadoc注释必须直接位于方法之前（两者之间没有换行符），而我不确定在@Override注释的正上方放置Javadoc注释是否会导致问题。

例如，这是否是常规做法？这样可以吗？

   /**
    * This is my method's javadoc comment.
    */
   @Override
   public boolean myMethod()
   {
      // do stuff
   }

- Tim

---

总有一个像你这样的人。我想知道的是惯例是什么，而不仅仅是它是否有效。 - Tim

Answer 1

是的，这种方法是正确的方式，我还没有看到另一种方式。 是的，这种方法有效。没有尝试过另一种方式。

   /**
    * This is my method's javadoc comment.
    */
   @Override
   public boolean myMethod()
   {
      // do stuff
   }

通常情况下，我不会为重写另一个方法的方法添加javadoc注释，特别是在实现接口时。标签@inheritDoc 在这里非常有用，可以在不费太多功夫的情况下分发文档。但这只针对此示例，您也可以添加其他注释。

- Markus

---

我不同意覆盖方法不应该被记录。这可能适用于已实现的接口方法，但覆盖类方法的文档可以说明方法行为发生了什么变化。当然，使用 @inheritDoc Javadoc 标签可以避免大量打字，但在覆盖方法上不应省略文档记录。 - buc

基本上我同意你的观点，所以稍微更新了我的回答。但我认为Javadoc用于记录方法做什么，而不是怎样做。改变某些事情的做法完全可以，但这种改变不应违反超类定义的契约，否则就需要更改Javadoc。这就是为什么我认为写每个方法的Javadoc并不是必要的原因。 - Markus

Answer 2

是的，它会正常工作。例如，在openjdk的java.lang.String源代码中，他们在@Deprecated注释的顶部使用javadoc。

- Tudor