用@see写正确的javadoc？ [英] Writing proper javadoc with @see?

问题描述

如何正确使用 @see javadoc？

How do I use the @see javadoc properly?

我的意图是拥有一个抽象类抽象方法。这些方法有javadoc注释。
现在，如果我扩展抽象类，我会覆盖这些方法，并希望使用 @see 。

My intention is to have an abstract class with abstract methods. These methods have javadoc comments. Now if I extend the abstract class, I override the methods and want to use @see.

但是对于所有参数，例如返回 @see 链接似乎不起作用。 Eclipse仍然抱怨期望的@return标签。

But for all params, eg for return the @see link does not seem to work. Eclipse still complains that expected @return tag.

那我该如何使用它？

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

class MyImpl extends MyBase {

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

推荐答案

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

For the purpose of including the documentation from a superclass you should use {@inheritDoc} not @see.

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

Then you get the docs of the superclass. You can add to it, and you can override stuff like @param and @return if you need to.

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) { .. }
}

这篇关于用@see写正确的javadoc？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！