What is the preferred method of commenting javascript objects & methods [closed]

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

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;
}

Answer 2

The simpler the better, comments are good, use them :)

var something = 10; // My comment

/*
Lorem ipsum dolor sit amet, consectetur adipisicing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco
nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor
in reprehenderit in voluptate velit esse cillum dolore eu
fugiat nulla pariatur.
*/

function bigThing() {
    // ...
}

But for autogenerated doc...

/**
 * Adds two numbers.
 * @param {number} num1 The first number to add.
 * @param {number} num2 The second number to add.
 * @return {number} The result of adding num1 and num2.
 */
function bigThing() {
    // ...
}

Answer 3

Yahoo offers YUIDoc.

It's well documented, supported by Yahoo, and is a Node.js app.

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.

Answer 4

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 5

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.