Java文档实践，其重写方法的返回类型是重写方法的返回类型的子类

Question

I am writing Javadoc for a new package where I am facing the dilemma mentioned in the title.

I have base class method defined as,

class Vector<E> {
  ..
  public abstract Vector<E> add(Vector<E> v);
  ..
}

The overriding method is defined as,

class IntVector extends Vector<Integer> {
  ..
  @Override
  public IntVector add(Vector<Integer> v) {
  ..
  }

The overriding method does not change the behavior except for the return type. I know that redundant documentation is not desirable for overridden methods. However in this case it makes sense for the overriding method to have its own documentation, at least for the return type. What is the best practice for such situations? Just copy the specification over or is there a good way to avoid duplication?

Answer 1

As pointed out in the comments, if there is nothing special about the different return type and you only want to point out that it is different, then there is normally no need to do this explicitly. The javadoc and the IDE code completion will indicate that the return type is different.

However, if you want to add additional information, then you can take a look at method comment inheritance :

When a main description, or @return, @param, or @throws tag is missing from a method comment, the javadoc command copies the corresponding main description or tag comment from the method it overrides or implements (if any).

So in your case you could write:

/**
 * @return A verify special IntVector
 */
@Override
public IntVector add(Vector<Integer> v) {
    ...
}

And it would copy all missing information, such as the main description and the documentation for the v parameter from the overridden method.