Подробная информация о разнице между @see и @inheritDoc

87

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

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

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

Если я обязан плодоовощного JavaDoc я должен оставить его в этом, замените @seeс {@inheritDoc}, или превратить его в добросовестном JavaDoc как таковой:

/**
 * {@inheritDoc}
 */

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

java javadoc comments theUg
источник

Ответы:

143

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

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

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

Jtahlborn
источник
75
Вы должны использовать его только в том @inheritDocслучае, если собираетесь добавить в исходную документацию суперкласса. Если вы просто хотите, чтобы он был продублирован, Javadoc уже сделает это, отметив, что документация суперкласса применяется к переопределенному методу подкласса, поскольку подкласс не предоставил никакой дополнительной документации.
seh
4
Я создал документы с и без, @inheritDocи не вижу никакой разницы. Даже без этого @inheritDocя вижу, что Javadoc производного класса был добавлен к базовому классу.
randominstanceOfLivingThing
Я пришел сюда, потому что checkstyle жалуется, что «метод не предназначен для расширения». Хорошей идеей может быть использование, @inheritDocа затем добавление некоторой документации для конкретной реализации, например, как он реализует / перезаписывает родительский метод, и особенно ПОЧЕМУ он делает это именно так.
Бен