JavaDocs的最佳实践 - 接口,实现或两者兼而有之？

Question

我有一个DAO接口和DAO的实现.接口中的JavaDocs是Netbeans向实现DAO方法的客户端显示的内容.

显然我需要在界面中维护JavaDocs.但是它的实施呢？一方面,将它们放在那里很方便,但另一方面,它是重复的,需要它们保存在两个地方.

只是想知道其他Java开发人员做了什么.

Answer 1

如果实现方法没有提供自己的Javadoc,那么仍然会有一个指向接口方法文档的链接.我从未理解为什么Eclipse会插入, /* (non-Javadoc) @see ... */因为Javadocs会自动引用接口的文档.

例:

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.getNameJavadocs是:

getName

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

Answer 2

在我的项目中，Eclipse 自动创建文档，如下所示：

     /* (non-Javadoc)
     *  @see com.comp.SomeInterface#method(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)
     */
    @Override
    public void method(HttpServletRequest arg0, HttpServletResponse arg1)
            throws Exception {
        // TODO Auto-generated method stub

    }

我们已经使用 Ant 任务创建了 javadoc，因此它创建了到界面的链接。