¿Cuál es el método preferido de comentar objetos y métodos JavaScript

Question

que estoy acostumbrado a Atlas donde el preferido (por lo que sé) método es utilizar los comentarios XML como:

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

recientemente he estado buscando en otras bibliotecas javascript 3 ª parte y veo sintaxis como:

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

como beneficio adicional, por favor, hágamelo saber si hay algún generadores API para JavaScript que podría leer el estilo comentando 'preferido'.

Answer 1

Hay 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

El uso del comentario triple en el primer ejemplo se usa realmente para herramientas externas de documentación XML y (en Visual Studio) soporte intellisense. Sigue siendo un comentario válido, pero es especial :) El 'operador' de comentario real es // La única limitación es que se trata de una sola línea.

El segundo ejemplo utiliza el comentario de bloque de estilo C que permite hacer comentarios a través de varias líneas o en el medio de una línea.

Answer 3

Trate de pegar el siguiente en un archivo JavaScript en Visual Studio 08 y jugar un rato con él:

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 en abundancia!

Más información sobre esto (incluyendo cómo hacer referencia a los archivos javascript externos, para usar en bibliotecas grandes) se puede encontrar en Scott Gu's blog.

Answer 4

Yahoo ofrece YUIDoc.

Está bien documentado, es compatible con Yahoo y es una aplicación Node.js.

También utiliza una gran cantidad de la misma sintaxis, por lo que no se necesitarán realizar muchos cambios para pasar de uno a otro.

Answer 5

Cuanto más simple sea el mejor, los comentarios son buenos, se utiliza :)

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

Pero para doc autogenerado ...

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