What should have javadoc in Java ?

Question

What should be documented by javadoc comments (classes, methods, constructors and fields? Or only classes methods and constructors?)? Is there any convention about that ?

Please provide links to relevant resources in your answer whenever possible. Thank you

EDIT: The question is not about how is it usualy done or what is logical to comment with javadoc. The question is what can be found about this matter in any official Sun/Oracle documents (guidelines about writing javadoc, conventions, specifications and so on). Also please do not answer about how should the javadoc comments look like, the question is specifically about what should be commented, not how.

Answer 1

Javadoc is to document the public API of your code.

In a nutshell, you need to document all your public and protected classes, methods, constructors, and fields (because they are accessible to your users).

You need to describe what a method does, not how it does it. Of course, if implementation details result in interesting side-effects, for example performance characteristics, and also usage limitations, those should be mentioned.

Oracle has official guidelines on "How to Write Doc Comments for the Javadoc Tool".

Answer 2

Imagine showing the code to someone else who is familiar with the programming language, but not your project. Whichever parts you feel the need to explain as you're watching him review it should be documented.

similar question on programmers.SE: Should you document everything or just most?

Answer 3

Simple and general rules for javadoc as mentioned by Thilo and also from here should be as follows :

Javadoc Guidelines

General Rules

• All public and protected methods must have full documentation
• Trivial getters and setters are exempted from this rule. Doing
  anything but returning or changing a
  variable in a getter or setter should be documented.
• Private methods with non-obvious implementations should have enough
  documentation to allow other
  developers to debug them

Official guidelines are found here : How to Write Doc Comments for the Javadoc Tool