Qual è il metodo preferito di commentare oggetti e metodi JavaScript

Question

a cui sono abituato atlante in cui la preferita (da quello che so) metodo è quello di utilizzare i commenti XML, quali:

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

Recentemente sono stato cercando in altri 3rd party librerie javascript e vedo sintassi del tipo:

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

come bonus, per favore fatemelo sapere se ci sono dei generatori di API per JavaScript in grado di leggere il 'preferito' stile commentando.

Answer 1

C'è 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

L'utilizzo del triplo commento nel primo esempio viene effettivamente utilizzato per strumenti di documentazione XML esterni e (in Visual Studio) per il supporto intellisense. È ancora un commento valido, ma è speciale :) Il commento attuall 'operatore' è // L'unica limitazione è che è per una singola riga.

Il secondo esempio utilizza il commento del blocco in stile C che consente di commentare su più righe o nel mezzo di una riga.

Answer 3

Prova incollando il seguente in un file javascript in Visual Studio 08 e giocare con essa:

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 bizzeffe!

Ulteriori informazioni su questo (compreso il riferimento ai file javascript esterni, per l'uso in librerie di grandi dimensioni) sono disponibili su Scott Gu's blog.

Answer 4

Yahoo offre YUIDoc.

È ben documentato, supportato da Yahoo ed è un'app Node.js.

Inoltre utilizza molto la stessa sintassi, quindi non dovrebbero essere apportate molte modifiche per passare dall'una all'altra.

Answer 5

Il più semplice il meglio, i commenti sono buone, lo usa :)

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

Ma per doc generato automaticamente ...

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