What is the preferred method of commenting JavaScript objects and methods?

EvilSyn_6350 0
Viewed 74505

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 third-party JavaScript libraries and I see syntax like:

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

As a bonus, are there API generators for JavaScript that could read the 'preferred' commenting style?

comments javascript
5 Answers

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

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.

user_181460

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.

Jim_Burger_201640

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.

roosteronacid_209460
Related