Javascript – the preferred method of commenting javascript objects & methods


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.

Best Solution

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;