Java - 将javadoc与方法注释一起使用的惯例？

我有以下方法：Java - 将javadoc与方法注释一起使用的惯例？

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

如果我想添加一个javadoc这种方法，有没有关于如何做到这一点与具有@Override注释（或其他任何注解）沿着任何约定？

我问的原因是因为我读过javadoc注释必须直接在方法之前（两者之间没有新行），并且我不确定是否将@avidoc注释直接放在@Override注释之上会乱七八糟事情了。

这是传统的做法吗？这是否工作？

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

来源

2012-03-25 Tim

总有一个人。我想知道公约是什么，不只是它是否有效。 – Tim 2012-03-25 21:03:07

是的，这种方式是正确的方式，我没有看到相反的方向。是的，这种方式是有效的。没有尝试另一种方式。

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

但基本上我通常不会Javadoc注释实现接口时，添加到覆盖另一种方法一种方法，尤其是。标签@inheritDoc在这里很有帮助，可以毫不费力地分发文档。但是，这是特定于此示例，您也可以添加其他注释。

来源

2012-03-25 20:06:56 Markus

我不同意重写的方法不应该记录。这对于已实现的接口方法可能是正确的，但重写的类方法的文档可以说明方法行为中发生了什么变化。当然，通过使用'@ inheritDoc' Javadoc-tag可以避免很多输入，但IMO文档不应该在重写的方法上省略。 – buc 2012-03-25 20:15:31

基本上我同意你的看法，因此稍微更新了我的答案。但我认为javadoc是用于记录**一种方法的功能，而不是**如何完成。改变方式如何完成是非常好的，但是这种改变不应该违反超类定义的合约，这会导致需要改变javadoc。这就是为什么我认为为每种方法编写javadoc并不是必需的。 – Markus 2012-03-25 20:25:05

是的，它会正常工作。例如，在来自openjdk的source code of java.lang.String中，他们在@Deprecated注释之上使用javadoc。

来源

2012-03-25 20:08:39 Tudor

Java - 将javadoc与方法注释一起使用的惯例？

回答

相关问题