Практика документации Java для переопределяющих методов, чей тип возврата является подклассом возвращаемого типа переопределенного метода

Question

Я пишу Javadoc для нового пакета, где я сталкиваюсь с дилеммой, упомянутой в заголовке.

У меня есть метод базового класса, определенный как,

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

Метод переопределения определенas,

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

Переопределяющий метод не меняет поведение, кроме возвращаемого типа.Я знаю, что избыточная документация нежелательна для переопределенных методов.Однако в этом случае для переопределенного метода имеет смысл иметь собственную документацию, по крайней мере, для возвращаемого типа.Какова лучшая практика для таких ситуаций?Просто скопируйте спецификацию или есть хороший способ избежать дублирования?

Answer 1

Как указано в комментариях, если нет ничего особенного в другом типе возвращаемого значения, и вы хотите только указать, что он отличается, то обычно нет необходимости делать это явно.Завершение javadoc и кода IDE будет означать, что тип возвращаемого значения отличается.

Однако, если вы хотите добавить дополнительную информацию, вы можете взглянуть на наследование комментариев метода :

Если в комментарии метода отсутствует основное описание или тег @return, @param или @throws, команда javadoc копирует соответствующее основное описание или комментарий тега из метода, который она переопределяет или реализует (если есть).

Итак, в вашем случае вы могли бы написать:

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

И он скопировал бы всю недостающую информацию, такую ​​как основное описание и документацию для * 1014.* параметр из переопределенного метода.