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

It works for me. I can hover and F2 on MyImpl.myFunc and see the javadoc I write on MyBase.myFunc. — ewan.chalmers, Jun 20 '12 at 14:22
"@see" does not mean - no need to document here. And mostly it does not mean link to - for that purpose @link may be use as outlined in https://stackoverflow.com/questions/5915992/how-to-reference-a-method-in-javadoc — Wolfgang Fahl, Jun 27 '19 at 04:19

score 21 · Accepted Answer · answered Jan 06 '17 at 16:27

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

Writing proper javadoc with @see?

1 Answers1

Linked