I am reorganizing my JavaScript library to use a single namespace. We have ~ 200 modules that have previously established themselves as jQuery plugins or on a global object (bad). In the past, to get Intellisense, I added module links for each module (from which I wanted Intellisense) as
at the beginning of each module file.
Everything related to the previous dispensation was erroneous, fragile and inelegant.
I hope to fix this in a new dispensation. One of the main goals of this refactoring is to make it easier for beginners to work in the library, and Intellisense is of great benefit.
Currently, I am merging all * .js files into one nameSpace-vsdoc.js file. Each method of each class is documented using the vsdoc syntax. Each module uses this single vsdoc link. This works fine, but it's awkward. Intellisense works 300% better than before, but it's still not accurate enough. It skips most of my xml documentation and doesn’t very well learn methods / classes that even return somewhat complex objects.
YUI Doc offers a way to create documentation from JsDoc syntax, but this does not help Intellisense. Deep soul-googling did not reveal any third-party solutions.
Are there any tools for generating VsDocs in a more intelligent way of Intellisense?
UPDATE:
After some in-depth thought, testing, and incremental refactoring, I have a basic namespace that looks like this jsFiddle .
This allows me to write freely pair modules in self-executing functions that register the required methods in the namespace. All modules start with:
I generate this vsdoc using a simple Perl script that I hooked up to the VS 2010 build event:
use strict; my $dir = $ARGV[0]; my $destfile = "$dir\\js\\NameSpace-vsdoc.js"; unlink($destfile); my $js = ""; $js .= extractFile("$dir\\js\\_first-vsdoc.js"); $js .= extractFile("$dir\\js\\NameSpace.js"); $js .= extract("$dir\\js\\modules"); #Add additional directories as needed $js .= extractFile("$dir\\js\\_last-vsdoc.js"); open(VSDOC, "> $destfile") or die("Cannot open vsdoc file: $destfile ; $!"); print VSDOC $js; close(VSDOC); sub extract { my $ret = ""; my $path = $_[0]; opendir(JSDIR, $path) or die("Cannot open js directory: $path ; $!"); while((my $filename = readdir(JSDIR))) { if($filename =~ /.*\.js$/ && $filename !~ /-vsdoc/ && $filename !~ /_first/ && $filename !~ /_last/ && $filename !~ /.min\.js/) { $ret .= extractFile("$path\\$filename"); } } closedir(JSDIR); return $ret; } sub extractFile { my $ret = ""; my $filename = $_[0]; open(JSFILE, "$filename") or die("Cannot open js file: $filename ; $!"); while((my $line = <JSFILE>)) { if($line !~ m/-vsdoc\.js/ ) { $ret .= $line; } } close(JSFILE); return $ret; } printf("Finished generating NameSpace vsdoc.\n");
The _first-vsdoc.js and _last-vsdoc.js files transfer all contents to the self-executing function. Then I pass the resulting vsdoc to the Closure compiler, YUI Compressor and Uglify if necessary / appropriate.
This process works much better than before, but it is still not without flaws.
Starting from scratch, in NewModule.js, which references NameSpace-vsdoc.js, I get proper Intellisense:
Ns.register()
However, when I define NewModule.js as (and compile):
(function _alertClosure() { Ns.register('alert', function alert(someText) {
I do not get proper Intellisense for:
Ns.alert() //no Intellisense help
which is bewildering because it works so well on namespaces. I am forced to do this:
Ns.alert = Ns.alert || Ns.register('alert', function ....
Compile and suddenly (obviously) Intellisense works as expected.
Intellisense works with chain methods using jQuery vsdoc (which I carefully studied when building this process), and jQuery does not resort to tricks yx = yx || new x() yx = yx || new x() to make this happen.
So here is the revised question: From a structural point of view, the only distinguishable difference that I can perceive between jQuery vsdoc and my own is that jQuery collects the entire namespace inside the same closure. My namespace and each of my modules are wrapped in separate locks. For comparison, my vsdoc looks like a long string of self-executing functions.
There is too much risk associated with the rejection of the closing scheme / module; and it is difficult to test the hypothesis in isolation. Intellisense works well when the library is small and therefore cannot generate thousands of Javascript Intellisense messages: C: \\ js \ NameSpace-vsdoc.js (40:16): Object required "errors.
Ideas?