[thayne]

I find it pretty frustrating to have the documentation in a different file from the source code.

When maintaining the code that means I have to go to a separate file to read what a function is supposed to do, or update the documentation.

And when reading the documentation, if the documentation is unclear, I have to go to a separate file to see what the function actually does.

Granted, the implementation can get in the way if you are just reading the documentation, but if you aren't concerned about the implementation, then as others have said, you can use generated documentation.