Javascript Intellisense, Documentation, & Visual Studio 2008 (Orcas)

Scott StultsSeptember 1, 2007

I’ve been working inside the quasi evil yet intriguing world of javascript for the last several weeks due to current projects and the web side of my BHAG project (Amplify.Net framework). I’ve been rethinking a lot things, including spinning the Javascript into its own opensource project that works with the framework and without the framework. I’ve also had to ask myself, how do I make this easy for developers to leverage/use? And how do go about streamlining the documentation process for javascript code.

In building this library, since I’m building most of my own controls in order to keep things simple and be able to wire them up to .NET server controls, I’m leveraging the Prototype Library so far, because its not bulky (yet), compared to the Asp.Net Ajax Library. Also css selectors are not yet available in the Asp.Net Ajax library, but they are planned for a future release.

I’ve also have been testing the new Javascript features of Visual Studio 2008 (Orcas). Don’t get me wrong, when I’m working in ruby, I’ve been digging the e-texteditor, which even has some features the mac version does not, like close all tabs and you can shift + tab code instead of shift + [. However, intellisense is a compelling feature when it comes to speeding up development, also having inline documentation bundled with intellisense is a win/win for developers.

Granted, Visual Studio 2008 Beta 2 (Orcas) has improved javascript intellisense, but there are still too many gotchas…

Intellisense Gotchas

Gotcha 1.) Visual Studio loses intellisense for all scripts if it is unable to parse one. If you load a script like prototype.js;, that doesn’t follow the rules Visual Studio can handle, it kills the intellisense for all other scripts that in the format Visual Studio can handle. ;

<script type="text/javascript" src="../javascripts/prototype.js"></script>
<script type="text/javascript" src="../javascripts/amplify.js"></script>

or

/// <reference path="prototype.js />
/// <reference path="amplify.js />

This is what happens when its working. javascript intellisense as it should be

This is what happens when you add a good library that Visual Studio can’t figure out. javascript-intellisence-broken

Gotcha 2.) Visual Studio crashes when you use dojo functions. If you have a complex library like dojo and you attempt to do something “dojo.style”, this crashes visual studio, possibly due to the fact that the dojo style function does both get and set? or its just too much script in the global namespace for visual studio to handle.

Gotcha 3.) Visual Studio is not able to do complex chaining of functions. I love the inheritance model of Prototype 1.6.0 RC. When you create a class using prototype, you do some thing like what is shown in the code sample below. Visual Studio doesn’t know what to make of the object “Amplify.MockWidget” and ends up killing any intellisense in the script and in any place you reference the script file would have the following code. You can even add xml comments and put in the type and visual studio isn’t currently smart enough to make light of that.

// visual studio can't make out the object type..
var Amplify.MockWidget = Class.create(Amplify.UI.Control, {
  load: function() {
    this.element = $(this.element);
    this.element.observe(
      "click",
      this.onClick.bind(this)
    );
  },

  onClick: function() {
    $log("hello world");
  }
}); // should be of type Function, but visual studio does not see that.

So what you end up having to do is creating classes using the Asp.Net Ajax style of coding, which tends be more verbose (and doesn’t seem as elegant to me).

Gotcha 4.) JSON style object declaration breaks intellisense. Visual Studio Intellisense, won’t allow you to access other properties/methods using the “this” keyword. So if you do the following, Visual Studio will not have the object’s functions/properties listed in the drop-down. So in the Define method below, you will not be able to see _specs when you type this.

var Specification = function(name, description, functionality) {
  this.name = name;
  this.description = description;
  this.functionality = functionality;
}
var Spec = {
  _specs: [],
  Define: function(specification) {
  ///<summary> Defines a new part of the specification </summary>
  ///<param name="specification" type="Specification"> a defined piece of the total spec. </param>
    this._specs.push(specification);
  }
}

Gotcha 5.) Visual Studio Intellisense relies on the Asp.Net Ajax framework concepts for determining object types. So if you want a class to show up as a class, you need to add __class: true or ObjectName.__class = true; or something to that effect for visual studio to recognize the object as a class. So rather than putting that overhead in the scripts, I’m making a second script that has all this type of meta data for intellisense purposes..

Gotcha 6.) Visual Studio finds errors with javascript. However, because you can’t currently reference a complex javascript file like prototype.js, since it removes all the enhancement of intellisense, Visual Studio finds methods that are not defined that you may use from a library and puts up an error in error panel. It would be nice if Visual Studio would provide a pragma for javascript similar to C#’s pragmas that would allow you to ignore these type of errors.

Documentation Gotchas

Since the great NDoc is no more due to the evils of developer expectations of the Microsoft world when it comes to open source .net projects, you’re pretty left with SandCastle if you go the route of xml comments. Now if you plan to leverage the intellisense of visual studio, you’re pretty much stuck with xml comments. The only other way around this is use something like Aptana which uses JsDoc style of comments. (the YUI library also uses this format.) However, I find JsDoc style of documents ugly and I want to minimize the burden of tweaking the styled pages not to mention I don’t feel like installing and running active pearl and creating yet another ugly dependency on a project.

Gotcha 1.) Parsing XML Comments In Javascript. SandCastle only parses xml documents, it does not go through code and pull out the xml format from the code files such as .js, .cs, .vb files. When you build your dll or exe, thats when visual studio pulls out those xml comments and puts them into one xml file. Right now SandCastle, nor Visual Studio handles parsing xml comments from javascript files.

Enter Bertand Le Roy’s Ajax Doc which parses out the xml comments in javascript files and puts them into one xml document. However… this brings up more gotchas.

Gotcha 2.) Ajax Doc requires extra dependencies. Ajax Doc uses the Asp.Net Ajax Library, which is an extra dependency on the project, however this Ajax Doc is totally written in Javascript, but requires Internet Explorer, probably for writing the xml file or something to that effect.

Gotcha 3.) Ajax Doc relies on Asp.Net Ajax Object Types. Ajax Doc only documents comments based upon the Asp.Net Ajax Object model. Which means functions who have declared class types of class, interface, enum, etc, are the only ones that get documented. So your classes must have those __class = true; or __enum = true; defined in your objects otherwise the Ajax Doc will skip your objects.

Gotcha 4.) Ajax Doc relies on the inheritance model of the Asp.Net Ajax library. This means that if you are using libraries like the new Prototype 1.6.0 RC, which has inheritance, Ajax Doc is not smart enough to be able to parse that inheritance model out to put into the xml comments file.

Gotcha 5.) Ajax Doc has limited tag parsing. Tags like <remarks> are not included, in fact the only thing it really handles at this point is on Bertand’s posting on Javascript xml comments.

In closing, I’m still digging the fact that the visual studio team is putting in better intellisense for javascript, however, I’m hoping one of them reads this in order to provide better support for javascript overall, since the style of javascript is so diverse. Even if you have rely on documenting your scripts to allow for this, I think this would push well documented libraries to evolve, rather than obscure scripts that are impossible to read.

track17 Naruto Bad Situation




More blog articles:


We've been Solr-istas since day one!

Our founder wrote the first book on Solr, now in 3rd edition. We've helped organizations from the US Patent and Trademark Office to Cisco build smarter search solutions with Solr.

Learn More about our Solr services.