java - JavaDocs 的最佳实践 - 接口(interface)、实现或两者兼而有之？

Question

我有一个 DAO 接口(interface)和 DAO 的实现。界面中的 JavaDocs 是 Netbeans 显示给实现 DAO 方法的客户端的内容。

显然，我需要在界面中维护 JavaDocs。但是它的实现呢？一方面，放在那里很方便，但另一方面，这是重复的，需要在两个地方维护。

只是想知道其他 Java 开发人员在做什么。

Answer 1

如果实现方法不提供自己的 Javadoc，仍然会有指向接口(interface)方法文档的链接。我一直不明白为什么 Eclipse 会插入 /* (non-Javadoc) @see ... */ 因为 Javadocs 会自动引用接口(interface)的文档。

例子:

public interface Named {
  /** Returns the name. */
  public String getName();
}

public class Thing implements Named {
  // note no Javadocs here
  public String getName() {
    return "thing";
  }
}

运行javadoc后，Thing.getName的Javadocs是:

getName

public java.lang.String getName()
    Description copied from interface: Named
    Returns the name.
    Specified by:
        getName in interface Named