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

comments, javascript

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

Problem

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?

Original source