我有一个 DAO 接口和 DAO 的实现。界面中的 JavaDocs 是 Netbeans 向实现 DAO 方法的客户端显示的内容。
显然,我需要在界面中维护 JavaDocs。但是它的实施呢?一方面,放在那里很方便,但另一方面,它是重复的,需要在两个地方进行维护。
只是想知道其他 Java 开发人员在做什么。
我有一个 DAO 接口和 DAO 的实现。界面中的 JavaDocs 是 Netbeans 向实现 DAO 方法的客户端显示的内容。
显然,我需要在界面中维护 JavaDocs。但是它的实施呢?一方面,放在那里很方便,但另一方面,它是重复的,需要在两个地方进行维护。
只是想知道其他 Java 开发人员在做什么。
如果实现方法不提供自己的 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.getName
的 Javadocs 为:
getName
public java.lang.String getName()
Description copied from interface: Named
Returns the name.
Specified by:
getName in interface Named
接口应该有合约的所有信息,基本上是方法做了什么,参数的描述,返回值等等。
除非接口描述中有一些额外的信息不清楚(很少有),否则实现文档应该简单地链接到接口方法。
这是我从栅栏的实现者和客户端发现的最有用的格式。
在我的项目中,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,因此它创建了到界面的链接。