我习惯了 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 生成器可以读取“首选”评论风格？
/**
* 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;
}
越简单越好，评论很好，用吧:)
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() {
// ...
}
在第一个示例中使用三重注释实际上用于外部 XML 文档工具和（在 Visual Studio 中）智能感知支持。它仍然是一个有效的注释，但它的特殊性:) 实际的注释“操作符”是 // 唯一的限制是它的单行。
第二个示例使用 C 样式的块注释，它允许跨多行或在一行中间进行注释。
尝试将以下内容粘贴到 Visual Studio 08 中的 javascript 文件中并使用它：
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);
};
智能感知丰富！
有关这方面的更多信息（包括如何引用外部 javascript 文件，以便在大型库中使用）可以在Scott Gu 的博客上找到。