He missed the distinction between in-line comments and API comments. Pretty much all skilled developers would agree that in-line comments should be minimized, and used only when necessary to explain the reasoning behind a particular design, or to clarify a complex section that can't be refactored. But for API functions which you intend other developers to use as black boxes, you need to provide extensive comments clearly explaining the purpose, inputs, outputs, error conditions, and maybe even some sample code.
That's documentation, not comments. Nothing hurts code readability more than huge chunks of markup (markup!) getting in the way of the code you need to read to maintain. Javadocxygenwhatever generates pretty web pages, but leads to write-only source files.
I appreciate the readability problem, but what would you propose as an alternative? In my experience, combining the code and documentation in a single file makes it much more likely that developers actually will update the documentation. Besides, any decent editor will hide the documentation if you don't want to see it.
How about abstraction? Draw a clean line between the API you're trying to document and the code that implements it, and make sure that comments for either don't cross-pollute. This is a good idea anyway.
I can't tell you how many automatically generated documentation trees I've seen that are utterly worthless. Documentation of public interfaces gets mixed in with usage notes on internal structures, and you don't know what you're supposed to use.
