Что должен иметь Javadoc в Java?

Question

Что должно быть задокументировано комментариями javadoc (классы, методы, конструкторы и поля? Или только классы, методы и конструкторы?)?Есть ли какое-либо соглашение об этом?

Пожалуйста, предоставьте ссылки на соответствующие ресурсы в своем ответе, когда это возможно.Спасибо

РЕДАКТИРОВАТЬ: Вопрос не в том, как это обычно делается или что логично комментировать с Javadoc.Вопрос в том, что можно найти по этому вопросу в любых официальных документах Sun / Oracle (руководство по написанию javadoc, соглашений, спецификаций и т. Д.).Также, пожалуйста, не отвечайте о том, как должны выглядеть комментарии javadoc, вопрос конкретно о том, что следует комментировать, а не о том, как.

Answer 1

Javadoc предназначен для документирования публичного API вашего кода.

В двух словах, вам нужно документировать все ваши открытые и защищенные классы, методы, конструкторы и поля (потому что они доступны вашим пользователям).

Вам нужно описать, что делает метод, а не как он это делает. Конечно, если детали реализации приводят к интересным побочным эффектам, например характеристикам производительности, а также ограничениям использования, следует упомянуть их.

У Oracle есть официальное руководство по " Как писать комментарии к документу для инструмента Javadoc ".

Answer 2

Простые и общие правила для Javadoc, упомянутые Thilo, а также из здесь должны быть следующими:

Руководство по Javadoc

Общие правила

• Все открытые и защищенные методы должны иметь полную документацию
• Тривиальные геттеры и сеттеры освобождены от этого правила.Выполнение
  чего-либо, кроме возврата или изменения переменной
  в получателе или установщике, должно быть задокументировано.
• Для частных методов с неочевидными реализациями должно быть достаточно документации
  , чтобы позволить
  разработчикамдля их отладки

Официальные инструкции можно найти здесь: Как писать комментарии к документу для инструмента Javadoc

Answer 3

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

аналогичный вопрос для программистов. SE: Должны ли вы документировать все или только большинство?