使用@see编写正确的javadoc文档？

Question

如何正确使用JavaDoc中的@see?

我想创建一个带有抽象方法的抽象类，并对这些方法添加JavaDoc注释。然后，如果我扩展该抽象类并覆盖这些方法，我希望能够使用@see。

但是对于所有参数，例如对于return，@see链接似乎无法正常工作。Eclipse仍会报告expected @return tag。

那么，我应该如何使用它呢？

public abstract class MyBase {
  protected abstract void myFunc();
}

class MyImpl extends MyBase {

  /**
   * @see MyBase#myFunc()
   */
  @Override
  protected void myFunc() { .. }
}

- membersound

---

它对我有效。我可以悬停并在MyImpl.myFunc上按F2，看到我在MyBase.myFunc上编写的javadoc。 - ewan.chalmers

"@see"并不意味着-这里不需要记录。而且大多数情况下，它并不意味着链接-为此，可以使用@link，如https://dev59.com/x2025IYBdhLWcg3wl3Em中所述。 - Wolfgang Fahl

Answer 1

为了包含来自超类的文档，您应该使用{@inheritDoc}而不是@see。

然后您将获得超类的文档。您可以添加内容，并且如果需要，可以覆盖@param和@return等内容。

public abstract class MyBase {
  /**
   * @param id The id that will be used for...
   * @param good ignored by most implementations
   * @return The string for id
   */
  protected abstract String myFunc(Long id, boolean good);
}

class MyImpl extends MyBase {

  /**
   * {@inheritDoc}
   * @param good is used differently by this implementation
   */
  @Override
  protected String myFunc(Long id, boolean good) { .. }
}

- Superole