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

/// /// 
\n\n
This is what happens when you add a good library that Visual Studio can’t figure out. 
\n\n
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.
\n\n
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.
\n\n


// visual studio can't make out the object type..\nvar Amplify.MockWidget = Class.create(Amplify.UI.Control, {\n  load: function() {\n    this.element = $(this.element);\n    this.element.observe(\n      "click",\n      this.onClick.bind(this)\n    );\n  },\n\n  onClick: function() {\n    $log("hello world");\n  }\n}); // should be of type Function, but visual studio does not see that.\n


\n\n
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).
\n\n
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.
\n\n


var Specification = function(name, description, functionality) {\n  this.name = name;\n  this.description = description;\n  this.functionality = functionality;\n}\nvar Spec = {\n  _specs: [],\n  Define: function(specification) {\n  ///
 Defines a new part of the specification \n  /// a defined piece of the total spec. \n    this._specs.push(specification);\n  }\n}\n


\n\n
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..
\n\n
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.
\n\n
Documentation Gotchas
\n\n
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.
\n\n
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.
\n\n
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.
\n\n
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.
\n\n
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.
\n\n
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.
\n\n
Gotcha 5.) Ajax Doc has limited tag parsing.  Tags like  are not included, in fact the only thing it really handles at this point is on Bertand’s posting on Javascript xml comments.
\n\n
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.
\n\n
track17 Naruto Bad Situation
\n\n