Question

As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.

Closed 10 years ago.

我习惯了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应用程序。

它还使用了许多相同的语法，因此不需要进行太多更改即可从一个语法转换到另一个语法。

Answer 4

The use of the triple comment in the first example is actually used for external XML documentation tools and (in Visual Studio) intellisense support. Its still a valid comment, but its special :) The actuall comment operator is // The only limitation there is that its for a single line.

第二个示例使用C风格的块注释，允许跨多行或在一行中间进行注释。

Answer 5

请尝试将以下内容粘贴到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的博客。

友情链接