validacion - ¿Cuál es el método preferido para comentar los objetos y métodos javascript

validar formulario javascript antes de enviar

Question

Estoy acostumbrado a atlas donde el método preferido (de 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 buscando en otras librerías javascript de terceros y veo sintaxis como:

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

Como beneficio adicional, comuníqueme si hay generadores de API para JavaScript que puedan leer el estilo de comentarios "preferido".

Answer 1

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 verdadero comentario ''operator'' es // La única limitación es que se trata de una sola línea.

El segundo ejemplo usa el comentario en bloque de estilo C que permite comentar a través de múltiples líneas o en el medio de una línea.

Answer 2

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!

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

Answer 3

Cuanto más simple sea el mejor, los comentarios son buenos, 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() {
    // ...
}

Pero para el documento 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() {
    // ...
}

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 muchos cambios para pasar de uno a otro.

Answer 5

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