Robert C. Martin’s book Clean Code contains the following:
HTML in source code comments is an abomination […] If comments are going to be extracted by some tool (like Javadoc) to appear in a Web page, then it should be responsibility of that tool, and not the programmer, to adorn the comments with appropriate HTML.
I kind of agree – source code surely would look cleaner without the HTML tags – but how do you make decent-looking Javadoc pages then? There’s no way to even separate paragraphs without using a HTML tag. Javadoc manual says it clearly:
A doc comment is written in HTML.
Are there some preprocessor tools that could help here? Markdown syntax might be appropriate.
I agree. (This is also the reason why I am -strongly- opposed to C#-style “XML comment blocks”; the Javadoc DSL at least provides some escape for top-level entities!). To this end I simply do not try to make the javadoc look pretty…
…anyway, you may be interested in Doxygen. Here is a very quick post Doxygen versus Javadoc. It also brings up the issues that you do 🙂