[kelnos]

No thank you. As someone who has to read code in addition to writing it, it's great to have the doc comments right there, so I don't have to open and search through another document.

There's also the issue of keeping things up to date: it's much more likely that a programmer is going to keep docs up to date if the doc is right there along with the code than if it's in a separate file.

Not to mention... XML... ugh, no, let's not.

[bodeadly]

I'm not a fan of XML either with the exception of one purpose which is document processing using XSLT. XSLT is THE correct way to generate documents. Markdown is extremely limited by comparison.

And I'm not suggesting that there would be no documentation in the code. Javadoc is written for consumers of the code being document. That is incorrect. The comments should be optimized for the developers of the code itself. And it should not explain what the code does if you can just read the code itself.

So again, IMO, javadoc is a mistake. It mixes up two largely different things.

Also, when you downvote someone, it's not supposed to be because you don't agree with their view. You downvote someone when they say something that does not contribute to the discussion. But do what you will ...