[jmreidy]

Swagger goes part of the way towards solving this problem, at least for REST apis: http://swagger.wordnik.com/. It's a little annotation heavy for me - I'm guessing you want something that's generated almost entirely from code introspection. And it obviously doesn't work for library code. But I think the UX for an implementer is a great one.

I do love Readme Driven Development (http://tom.preston-werner.com/2010/08/23/readme-driven-devel...), and Github helps here with its per-directory readme displays, but keeping up with these over the duration of a project is obviously a problem, as you note.