Подробности различия между @see и @inheritDoc

Question

Я просмотрел ссылку на JavaDoc, и пока я понимаю принципиальную разницу между @see (различные ссылки) и {@inheritDoc} (экспорт комментария JavaDoc суперкласса), мне нужно уточнить, как все реализовано на самом деле.

В Eclipse IDE, когда я выбираю "Создать комментарии к элементам" для унаследованного метода (из интерфейса или переопределения toString() и т. Д.), Он создает следующий комментарий

/* (non-Javadoc)
 * @see SomeClass#someMethod()
 */

Если мне нужно создать JavaDoc, я должен оставить его на месте, заменить @see с {@inheritDoc} или включите его в подлинный JavaDoc как таковой:

/**
 * {@inheritDoc}
 */

И когда я это сделаю, должен ли я все еще сохранять флаг метода class#?

Answer 1

Прежде всего, вы должны удалить оригинальный шаблон Eclipse, потому что это просто шумный мусор. Либо вставьте значимые документы, либо вообще ничего не ставьте. Но бесполезное повторение очевидного использования шаблонов IDE просто загромождает код.

Во-вторых, если вам необходимо создать Javadoc, то вы должны начать комментарий с /**, В противном случае, это не Javadoc.

Наконец, если вы переопределяете, вы должны использовать @inheritDoc (при условии, что вы хотите добавить к оригинальным документам, как заметил @seh в комментарии, если вы просто хотите дублировать исходные документы, то вам ничего не нужно). @see действительно должен использоваться только для ссылки на другие связанные методы.