Was die bevorzugte Methode der Kommentierung JavaScript-Objekte und Methoden ist

Question

ich Atlas gewohnt bin, wo die bevorzugten (von dem, was ich weiß) Methode ist xml Anmerkungen zu verwenden, wie zum Beispiel:

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

Vor kurzem habe ich gewesen Blick in andere 3rd-Party-JavaScript-Bibliotheken und ich Syntax sehen wie:

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

Als Bonus, lassen Sie es mich wissen, ob es irgendwelche API-Generatoren für JavaScript sind, die der ‚bevorzugte‘ kommentiert Stil lesen können.

Answer 1

Es gibt 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

Die Verwendung des Triple-Kommentars im ersten Beispiel wird tatsächlich für externe XML-Dokumentationstools und (in Visual Studio) IntelliSense-Unterstützung verwendet. Es ist immer noch ein gültiger Kommentar, aber sein besonderes :) Der aktuelle Kommentar 'Operator' ist // Die einzige Einschränkung ist, dass es für eine einzelne Zeile ist.

Das zweite Beispiel verwendet C-style-Blockkommentare, die Kommentare über mehrere Zeilen oder in der Mitte einer Zeile ermöglichen.

Answer 3

Versuchen Sie Folgendes in eine JavaScript-Datei in Visual Studio 08 und spielen, um mit ihm Einfügen:

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); 
}; 

Intellisense in Hülle und Fülle!

Weitere Informationen dazu (einschließlich, wie externe Javascript-Dateien zu referenzieren, für die Verwendung in großen Bibliotheken) finden Sie unter Scott Gu's blog.

Answer 4

Yahoo bietet YUIDoc.

Es ist gut dokumentiert, von Yahoo unterstützt und ist eine Node.js App.

Es verwendet auch eine Menge der gleichen Syntax, so dass nicht viele Änderungen vorgenommen werden müssten, um von einem zum anderen zu gehen.

Answer 5

Je einfacher die besten, Kommentare gut sind, verwendet es :)

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

Aber für automatisch generierte 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() { 
    // ... 
}