API docs as comments in comments in code look like a nice idea.
Until someone actually writes a comprehensive documentation in there: several paragraphs with code examples. When doc comments take most of the file and gets difficult to find the code, I'm no longer sure it's a good idea to have the two in the same place.