Brennan’s Blog

As I work on JavaScript I often consult with Google to find documentation on which functions are available and how they work. Sometimes I find the answer right away and other times it takes more effort to find the right answers. I really want it to be easier and faster to find the right answers quickly so I started work on a Tool Window that I call JavaScript Browser that integrates within Visual Studio 2008. The work done by James Hart to automatically generate the XML Doc Comments from the jQuery XML documentation is compelling. I have been tossing around idea of making the format of the jQuery XML documentation the format that I would use directly for the JavaScript Browser, but it may be limiting for other script libraries that work in very different ways.

The format I am leaning towards is the schema used by Visual Studio 2008 for the XML Doc Comments that were covered by Bertrand Le Roy. In addition to that schema I would wrap it with information about the current library such as name, version and potentially a list of dependencies that would refer to the name and minimum version. The jQuery documentation lists the version when a function was first introduced. That could be useful if I were to have a single jQuery definition that covers all versions instead of a definition for each version. In terms of pure effort, it may be easier to independently document each version by simply updating the definition each time one comes out. Once I have the format worked out I plan to publish them at XmlDocComments.com where the tool will be directed when the Get Definition Files link is clicked. I intend for this to be a community site where users can submit and share their definition files and help with updating files that are already there. I envision it working much like the Firefox extensions system.

In addition to supporting the JavaScript Browser, the Script Library Definitions will be used to generate stubs like the jQuery stub that I created to give the developer Intellisense support. I also expect that other formats will be generated as well, such as the slick jQuery API Browser. I actually considered just creating a Tool Window for Visual Studio that simply wrapped the jQuery API Browser, but it is limited to just jQuery currently and does not really fit well in different docking scenarios. The JavaScript Browser works well to dock horizontally or vertically and it will save your preferences so it is displayed consistently.

What is ready so far was easy enough to build. Now defining and creating the definition files will be the bulk of the effort. I plan to start out with the scripts I am actively using, like jQuery, jQuery UI, and jQuery Dimensions. Later I would like to document Prototype, Scriptaculuous, MochiKit and other popular libraries. I also think it makes sense to also document the core classes like Object and Array along with the other core types. Once the definition files are detailed enough I would like to engage the communities supporting these popular libraries and see where we can bring better tooling support to tools beyond Visual Studio, such as Eclipse. With a solid XML format it will be possible to generate the necessary formats for any output format.

I am interested in feedback on this effort. Please post your comments.