Javascript: HTML documentation and Intellisense for Visual Studio

Problem: I want to generate HTML documentation for my JavaScript files and have intellisense support in Visual Studio. I do not want to write massive comment blocks to support this.

Solution: Write javadoc style comments for jsdoc toolkit per standard practice. The rest can be easily automated.

Generate the HTML documentation using your favorite template. Generate stubbed code with XML doc comments using the vsdoc template. Put a reference comment in your javascript file pointing to the generated XML doc comments file and bang! You've got the intellisense support, documentation in HTML, and you didn't have to write massive comments in two different formats on top of the code (which says the same thing, again).

The vsdoc template is part of a fork of the jsdoc toolkit. You can find it at http://code.google.com/p/jsdoc-toolkit-vsdoc/

Be sure to generate the HTML documentation and the vsdoc documentation into two separate folders. You don't want them overwriting each others index.html and other files.

Adding a reference to the XML doc commented files in your JavaScript source files is easy and only takes one line of code. Find the generated file you want to reference, say it was called OpenLayersAll.js and it could be found by a path relative to your source file called atropa.listFileNames. All you need to add to your file is a comment like the one in the first line of the example below. Note that you have to use three slashes to mark the comment or it won't work.

/// <reference path="vsdoc-generated-files/OpenLayersAll.js" />
/**
 * Gets a list of files and directories as an array from a given path.
 * @author <a href="mailto:matthewkastor@gmail.com">
 * Matthew Christopher Kastor-Inare III </a><br>
 * ☭ Hial Atropa!! ☭
 * @version 20130112
 * @function
 * @param {String} sourcePath The directory you want to get the contents of.
 * @returns {Array} Returns an array populated with the directories contents or an empty array.
 */
atropa.listFileNames = function listFileNames(sourcePath) {
    "use strict";
    var fs, files, sources, x;
    fs = require('fs');
    files = fs.list(sourcePath);
    sources = [];
    for(x in files) {
        if(files.hasOwnProperty(x)) {
            if(String(files[x]).indexOf('.') !== 0) {
                sources.push(String(files[x]).trim());
            }
        }
    }
    return sources;
};

For more information about XML doc comments in visual studio go to http://msdn.microsoft.com/en-us/library/bb514138.aspx