Swagger goes part of the way towards solving this problem, at least for REST apis: <a href="http://swagger.wordnik.com/" rel="nofollow">http://swagger.wordnik.com/</a>. 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.<p>I do love Readme Driven Development (<a href="http://tom.preston-werner.com/2010/08/23/readme-driven-development.html" rel="nofollow">http://tom.preston-werner.com/2010/08/23/readme-driven-devel...</a>), 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.
You <i>can</i> repurpose Docco as a running commentary for library usage or for examples. This combines the readability of Docco with the awesome usefulness of usage examples.<p>It also allows you to easily run your example code as part of your test suite. Nothing more frustrating than broken example code.<p>e.g. <a href="http://dev.groupdock.com/kin/" rel="nofollow">http://dev.groupdock.com/kin/</a>