Writing XML docs for JavaScript
/One of the really nice thing about self-documenting code came from (as far as I'm aware, although they probably borrowed it from elsewhere) Java's javadoc. In .NET this was again borrowed.
I've read a few articles recently about VS.NET 2008 inferring javascript 'doc' from javascript code, and it got me thinking.
At the end, the purpose of self-documenting code is so that fellow developers (most likely your colleagues working late or a maintainer a few years later) don't have to second-guess what a method is doing. And you really don't want them to be calling you at 11pm in the evening. It stuffs you up for the evening and it makes you guilty that they are still at work that late.
There are two links I've read that talks in detail how intellisense for javascript is produced from reading javascript. I'll link them below.
http://weblogs.asp.net/scottgu/archive/2007/06/21/vs-2008-javascript-intellisense.aspx
http://weblogs.asp.net/bleroy/archive/2007/04/23/the-format-for-javascript-doc-comments.aspx
Both are very fascinating. Ideally javascript libraries like JQuery or Prototype (and others) should implement code commenting, as they ship with a compressed version anyway that has all the commenting stripped.
Perhaps it's possible to 'inject' code comments into jquery source code from their online API:
- download latest jQuery.Uncompressed
- grab a copy of the jQuery API
- for each function in jQuery js - following the rules from bleroy above, insert API
- happy jQuery intellisense in VS.NET 2008 :-)
- commit to internal source control
- repeat process for each new version of jQuery
jliu
