Qual è il metodo preferito per commentare oggetti javascript & amp; metodi [chiuso]

Question

Sono abituato ad atlanti in cui il metodo preferito (da quello che so) è usare commenti xml come:

/// <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 ho cercato altre librerie javascript di terze parti e vedo una sintassi come:

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

Come bonus, per favore fatemi sapere se ci sono generatori di API per JavaScript in grado di leggere lo stile di commento "preferito".

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

Più semplice è, meglio i commenti sono buoni, usali :)

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

Answer 3

Yahoo offre YUIDoc .

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

Utilizza anche molta della stessa sintassi, quindi non dovrebbero essere apportate molte modifiche per passare dall'una all'altra.

Answer 4

Prova a incollare quanto segue in un file javascript in Visual Studio 08 e gioca con esso:

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

Ulteriori informazioni al riguardo (incluso come fare riferimento a file javascript esterni, da utilizzare in librerie di grandi dimensioni) sono disponibili su blog di Scott Gu .

Answer 5

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

Il secondo esempio usa i commenti ai blocchi in stile C che consentono di commentare su più righe o nel mezzo di una riga.