¿Cuál es el método preferido para comentar objetos y métodos de JavaScript? [cerrado]

Question

Estoy acostumbrado al atlas donde el método preferido (por lo que sé) es usar 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 investigando otras bibliotecas de JavaScript de terceros y veo una sintaxis como:

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

Como beneficio adicional, avíseme si hay algún generador de API para JavaScript que pueda leer el estilo de comentarios "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

Cuanto más simples mejor, los comentarios son buenos, úsalos :)

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 documentos generados automáticamente...

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

Ofertas de Yahoo YUIDoc.

Está bien documentado, respaldado por Yahoo y es una aplicación Node.js.

También utiliza gran parte de la misma sintaxis, por lo que no sería necesario realizar muchos cambios para pasar de uno a otro.

Answer 4

Intente pegar lo siguiente en un archivo javascript en Visual Studio 08 y juegue 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!

Puede encontrar más información sobre esto (incluido cómo hacer referencia a archivos javascript externos, para usar en bibliotecas grandes) en El blog de Scott Gu..

Answer 5

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

El segundo ejemplo utiliza comentarios en bloque estilo C que permiten comentar en varias líneas o en medio de una línea.