Java从接口或超类注释函数

Question

在尝试遵循正确的Java doc注释实践时，在编写扩展基类或实现接口的类时，如何为已在接口规范或基础中注释的函数提供注释类？我只是简单地复制并粘贴基类或接口的注释吗？这种方法似乎反直觉。

Answer 1

最好使用@inheritDoc而不是界面中评论的手动副本。

如果方法的用户可能感兴趣，我会不时地描述实施的细节。但是如果你问我，也可以不写评论。

Answer 2

永远不要复制和粘贴评论。否则，当修改任何内容时，很难准确地同时更新所有这些内容。复制注释可能比复制代码更糟糕，因为编译器不会注意到是否有任何不一致。

类中方法的注释应记录该方法的作用，而不是来自其基类或正在实现的接口的重写方法，并且决不是派生类中的哪些方法可能正在做什么。

最重要的是：不要评论不需要评论的内容。诸如参数类型等明显的东西将由Javadoc自动生成。

Answer 3

如果没有指定其他的话，Javadoc默认继承父描述，如果你决定覆盖它是一个javadoc，因为在这种情况下，这种方法的实现/覆盖是如此重要/不同，它＆＃34;值得＆＃34; 自己的javadoc。

IFF你想保留两者，我通常做的是通过将javadoc添加到本地＆＃34;元素＆＃34;来覆盖它。 （类/方法），然后添加@see引用其父＆＃34;元素＆＃34;