什麼是評論

Question

我已經習慣了阿特拉斯其中優選（據我所知）的方法是使用XML註釋，如JavaScript對象和方法的首選方法：

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

在第一個示例中使用三元註釋實際上用於外部XML文檔工具和（在Visual Studio中）intellisense支持。它仍然是一個有效的評論，但它的特殊:)實際評論'運營商'是// 唯一的限制是它的一條線。

第二個示例使用C風格塊註釋，它允許跨多行或在行的中間進行註釋。

Answer 3

嘗試粘貼以下到一個JavaScript文件在Visual Studio 08和玩它：

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's blog上找到。

Answer 4

雅虎提供YUIDoc。

這是有據可查的，由雅虎支持，並且是一個Node.js應用程序。

它也使用了很多相同的語法，所以不需要做太多的修改就可以從一個到另一個。

Answer 5

越簡單最好，評價都不錯，用它:)

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