What is the preferred method of commenting javascript objects & methods

Question

I'm used to atlas where the preferred (from what I know) method is to use xml comments such as:

/// <summary>
///   Method to calculate distance between two points
/// </summary>
///
/// <param name="pointA">First point</param>
/// <param name="pointB">Second point</param>
/// 
function calculatePointDistance(pointA, pointB) { ... }

Recently I've been looking into other 3rd party javascript libraries and I see syntax like:

/*
 * some comment here
 * another comment here
 * ...
 */
 function blahblah() { ... }

As a bonus, please let me know if there are any API generators for JavaScript that could read the 'preferred' commenting style.

Answer 1

The use of the triple comment in the first example is actually used for external XML documentation tools and (in Visual Studio) intellisense support. Its still a valid comment, but its special :) The actuall comment 'operator' is // The only limitation there is that its for a single line.

The second example uses C style block commenting which allows for commenting across multiple lines or in the middle of a line.

Answer 2

Written in Perl, there's JSDoc

/**
 * Shape is an abstract base class. It is defined simply
 * to have something to inherit from for geometric 
 * subclasses
 * @constructor
 */
function Shape(color){
 this.color = color;
}

There's also a Java version, called the JSDoc Toolkit

Answer 3

Try pasting the following into a javascript file in Visual Studio 08 and play around with it:

var Namespace = {};
    Namespace.AnotherNamespace = {};

Namespace.AnotherNamespace.annoyingAlert = function(_message)
{
    /// <param name="_message">The message you want alerted two times</param>
    /// <summary>This is really annoying!!</summary>

    alert(_message);
    alert(_message);
};

Intellisense galore!

More info about this (including how to reference external javascript-files, for use in large libraries) can be found on Scott Gu's blog.

Answer 4

Yahoo just released YUIDoc.

It's well documented, supported by Yahoo, and written in Python. It also uses a lot of the same syntax, so not many changes would have to be made to go from one to the other.