如何为EJB及其接口编写Javadoc？

Question

请考虑以下示例

@Remote
public interface RegistrationService {
    public String register();
    public void unregister(String id);
    public void heartbeat(String id);
}

@Stateless
@Remote(RegistrationService.class)
public class RegistrationServiceBean implements RegistrationService {
    /* ... */
}

我有一个接口，比如说RegistrationService。这样，远程客户端就能够将自己注册到应用程序上。通过周期性地调用心搏()，它会发出它仍然活着的信号。

什么才是正确的方式来记录EJB及其接口？

例如：

接口

1. 该接口的用户可以将自己注册到应用程序上。然后，应用程序重新计算要在所有注册客户端均匀分布的内容。(这将涉及有关其他类的知识，例如重新计算类)
2. 该接口的用户能够注册自己，并通知服务器，如果它仍然连接。该实现使用此信息根据注册客户端的数量向底层系统发出任务(这不涉及其他类的知识，但从应用程序的角度来看并不是那么危险)。

班级

1. 当客户端注册、注销或心跳过期时，RegistrationService的此实现将在RecalculationClass中进行重新计算。这是必要的，因为数据必须在客户端之间均匀分布。

任何想法都值得赞赏。谢谢。

斯文

Answer 1

接口javadoc应该没有有关实现的信息。接口是关于什么，而不是如何。

例如，对于实现来说，完全忽略对接口方法的调用是有效的--即有一个空方法。

您的javadoc应该类似于：Notifies that the specified application is still alive。实现选择如何处理这些信息取决于它。

Answer 2

我想说的是，这取决于哪些信息对客户是重要的。如果重新计算对用户来说是完全不可见的，则可能不需要将其记录在接口中。如果客户端可以以其他方式查看重新计算的详细信息，则必须在这里指示，以便用户知道可能发生哪些交互。如果重新计算完全是内部的，并且可以在没有客户机注意的情况下进行更改，那么它不需要也不应该出现在接口描述中。