Javadoc - the wonderous addition to Java that made everything make sense or the thing that misleads and causes confusion?

Like most tools, Javadoc itself isn't inherently good or bad. It's existence as a tool is pretty brilliant but how useful vs confusing it is comes down to the developer using the tool.

So, what is Javadoc for? Well, the output is sometimes referred to as API doc and this gives us a clue. Javadoc is for documenting how to use the API. In many it comes down to providing some way of documenting the bits and pieces of OOP that the java language constructs left out. The most obvious one being pre/post conditions. Java doesn't provide any language constructs to handle these cases (unless you count assert, which really isn't the same thing as being able to compile time check preconditions and reflect postconditions). So what you get is documentation, in your API doc you say "This value must be non-null" or "This object must have been initialised by calling it's init()". This tells an API user what the preconditions are - albeit (see there's that word again) manually. Javadoc is a way of letting your API user know how to use the API.

What isn't Javadoc? Well, it's not where you should detail how the internals of your method works - thats for inline comments. Class level documentation is for explaining how to use the class as a whole and hopefully showing some examples. It's not to describe your understanding of the algorithm from xyz.com and how clever it is (and of course you are for being able to implement it) - just point at the site and explain how to use the class. For once, theres a reason. You don't document how the class/method works internally in the API documentation because:

1) It makes decomposition/abstraction less useful. If I have to grok how your class works internally while trying to work out how to use it's simple interface, then I haven't saved any space in my (tiny) mind to grok how my higher level complexity works.

2) Describing the internal logic gives the API user a chance to make assumptions about that implementation - which of course might change later without the API changing (no compile time warning that anything has changed). Yes the developer shouldn't make these assumptions, but why give them the chance?

3) You lose the message. Having a whole bunch of technical internal details described dilutes the information the developer actually needs - i.e. how to use the API. Harder to understand, more time wasted.

Javadoc is your friend, treat it right.