接口(interface)的 Javadoc 注释？

Question

我正在自学 Java，希望得到有关这个问题的反馈: 编写一个具有两种方法的 Java 接口(interface)，一种将两个 double 相加，返回总和，另一种将两个 double 相乘，返回结果。使用 JavaDoc 注释。

我错过了什么吗？在接口(interface)的 JavaDoc 注释中包含 @return 是否合适？

/**
 * This is an interface for basic math.
 */
public interface Math {

  /**
   * This method will be used to add two doubles.
   * @param a a value to be added
   * @param b the other value to be added
   * @return the sum of the two doubles
   */
  public double add(double a, double b);

  /**
   * This method will be used to multiply two doubles.
   * @param a a value
   * @param b the other value
   * @return the product of the two doubles
   */
  public double multiply(double a, double b);

}

Answer 1

Am I missing anything?

当前形式的 javadoc 中没有任何根本错误或“缺失”的内容。

Is it appropriate to include @return in the JavaDoc comment for the interface?

这绝对是合适的。接口(interface)是 API 的一种形式，API 方法返回值的含义是接口(interface)的基本方面。如果接口(interface)中未指定方法返回值的含义，则接口(interface)方法的调用者无法知道会发生什么。这使得接口(interface)编程变得困难。