whatwg.org предлагает такой формат документирования внешних <script> файлов:
<script src="cool-effects.js">
// create new instances using:
// var e = new Effect();
// start the effect using .play, stop using .stop:
// e.play();
// e.stop();
</script>
Лично для меня это открытие (то, что можно пихать полезняшки внутрь script[src] я знал, но тут же предлагается особый формат для документации)
Подробнее тут:
http://www.whatwg.org/specs/web-apps...ternal-scripts