The worst thing about HTML as docs is that you have to encode your code. You should just be able to write the code for the programming language you are using directly in the docs. Anything else is just nuts.
The MarkDown code character backtick is especially great for Java since it’s not a metacharacter in the Java syntax.
[1] I didn’t mean writing docs in Java itself, whatever that would look like.