Комментарии к программе Overridden in Java

Ответ 1

Ответ @SimonC объясняет, как утилита javadoc генерирует "унаследованную" документацию для переопределенных методов.

Вы также можете поместить явные javadocs в метод переопределения, и они будут иметь приоритет над унаследованными javadocs. Кроме того, если вы поместите тег {@inheritDoc} в метод переопределения javadocs, наследуемые комментарии будут включены в этот момент.

Чтобы ответить на этот вопрос:

Следует ли комментировать переопределенный метод или нет? Если да, то будет ли комментарий представлять собой Java Doc или простой комментарий?

На мой взгляд, если метод переопределения уточняет документированную семантику (контракт) переопределенного метода (или... не дай бог... разрывает контракт), то это заслуживает документирования в методе переопределения javadocs. Однако, если различия являются просто "деталями реализации", более подходящими являются простые комментарии (или комментарии).

(Тем не менее, практика включения комментария "non-javadoc", который ссылается на читателя обратно на переопределенный метод javadoc, является IMO, пустой тратой экранной недвижимости... когда я читаю исходный код.)

Ответ 2

Из Как написать комментарии к Doc для инструмента Javadoc:

Автоматическое повторное использование комментариев метода

Вы можете избежать повторного ввода комментариев к документу осознавая, как инструмент Javadoc дублирует (наследует) комментарии для методы, которые переопределяют или реализуют другие методы. Это происходит в трех случаях: когда метод в классе переопределяет метод в суперклассе Когда метод в интерфейсе переопределяет метод в суперинтерфейсе Когда метод в классе реализует метод в интерфейсе В первом два случая, если метод m() переопределяет другой метод, инструмент Javadoc создать подзаголовок "Переопределения" в документация для m(), со ссылкой к методу, который он переопределяет.

В третьем случае, если метод m() в данный класс реализует метод в интерфейс, инструмент Javadoc будет создать подзаголовок "Указано" в документации для m(), с ссылка на метод, который он реализует.

Во всех трех случаях, если Метод m() не содержит комментариев или теги, инструмент Javadoc также скопирует текст метода переопределения или реализации созданная документация для m(). Так что если документация переопределенного или реализованного метода достаточно, вы не нужно добавлять документы для м(). Если вы добавите какую-либо документацию комментарий или тег к m(), "Переопределяет" или "Указано" подзаголовком и ссылкой все равно будут отображаться, но текст не будет скопированы.