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.
