Javadoc comments considered harmful

Mark Hooijkaas, $Revision: 1.1 $, $Date: 2004/10/02 10:10:55 $

Javadoc documentation is good. However the practice to embed such documentation into java comments has some problems:

It makes the code more difficult to read.
It makes it hard to embed HTML into comments

This article will discuss these problems. This article will also propose a simple alternative to use the javadoc doclet approach to generate the same documentation, where the documentation is hold in a separate file, and the consistency od the documentation with the code is still checked.