JavaScript Documentation Sucks

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.

You can 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.

It also allows you to easily run your example code as part of your test suite. Nothing more frustrating than broken example code.

e.g. http://dev.groupdock.com/kin/