It's pretty important that you have written Javadoc comments into your source
code.

From time to time Sun has cheated and used Javadocs as a sort-of
pre-processor, with little things like /** @deprecated */ and /** @throws
RuntimeException */.  Fortunately since annotations came out we've seen a move
away from that.

While I do say it's fortunate we've moved away from burying program semantics
in Javadoc comments, there is an argument in favor of that behavior, emanating
from the perception of Javadocs as a form of "literate programming".