Comment by anatnom

The javadoc tool is useful for creating simple HTML documentation directly from the source code. But you end up choosing between making the documentation comments legible as source code or legible as HTML. If HTML javadoc is important to a project, this often means that HTML-in-java-comments will prevail, which in turn means that the developer experience of working on and maintaining those docs is poor. Eclipse and IntelliJ both do good HTML rendering of these comments in mouseover/etc displays, but it is quite annoying to open a file and then need to hover the mouse over the main type just to make the documentation legible.