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 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?

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() {     // ... }