评论javascript对象和方法的首选方法是什么

Question

我习惯使用atlas,首选(据我所知)方法是使用xml注释,例如:

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

最近我一直在寻找其他第三方JavaScript库,我看到的语法如下:

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

作为奖励,如果有任何可以读取"首选"评论风格的JavaScript API生成器,请告诉我.

Answer 1

有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

越简越好,评论很好,使用它们:)

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

但对于自动生成的文档......

/**
 * 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

雅虎提供YUIDoc.

它有很好的文档,由雅虎支持,是一个Node.js应用程序.

它也使用了许多相同的语法,因此不需要进行很多更改就可以从一个转换到另一个.