Writing proper javadoc with @see?

Question

How do I use the @see javadoc properly?

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.

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

So how can I use this?

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

class MyImpl extends MyBase {

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

Answer 1

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

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