I came across this in my usual readings today and thought I’d share. It looks like Microsoft is promoting (via numerous blog postings) ScriptDoc as a free way to generate XML documentation for JavaScript. It uses a style similar to the C# XML comments with one major difference: the comments actually go inside of the function instead of outside. Example (from the site):

this.getItem = function(index) {
    ///
    /// Gets an item in the filtered data by index.
    ///
    /// The index in the filtered data of the row to return.
    /// Null if the row was not found.
    return _filteredTable ? _filteredTable[index] : null;
}

Can I just say that I hate this format? I’m guessing that putting the comments inside of the function allows the processor to pull the comments out of the source code of a function more easily than trying to match outside comments to a following function…but I still don’t like it. I’ve tried writing this format and only got frustrated. It feels unintuitive compared to how I write comments for other languages (even C#).

I must say I really don’t like the direction that Microsoft is taking JavaScript and it saddens me to see free tools promoting Microsoft’s way rather than the way most people write JavaScript (documentation, for instance, more like JSDoc).