O que é o método preferido de comentar objectos e métodos JavaScript [fechado]

Question

Estou acostumado a atlas onde o preferenciais (pelo que sei) método é usar comentários XML, tais 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) { ... }

Recentemente eu estive olhando em outras bibliotecas javascript 3rd party e vejo sintaxe como:

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

Como um bônus, por favor deixe-me saber se existem geradores de API para JavaScript que poderia ler o estilo comentando 'preferido'.

Answer 1

Há 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

O mais simples, melhor, os comentários são bons, usá-los:)

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

Mas para doc gerado 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

YUIDoc .

É bem documentado, apoiado pelo Yahoo, e é um aplicativo Node.js.

Ele também usa um monte da mesma sintaxe, por isso não muitas mudanças teriam de ser feitas para passar de um para o outro.

Answer 4

Tente colar o seguinte em um arquivo JavaScript no Visual Studio 08 e brincar com ele:

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 abundância!

Mais informações sobre este (incluindo como fazer referência a javascript-arquivos externos, para uso em grandes bibliotecas) podem ser encontradas em Scott Gu blogue .

Answer 5

O uso do comentário triplo no primeiro exemplo é realmente usado para ferramentas de documentação XML externos e (em Visual Studio) suporte intellisense. Sua ainda um comentário válido, mas a sua :) O 'operador' especial comentário actuall é // A única limitação não é que a sua para uma única linha.

O segundo exemplo utiliza bloco estilo C comentar que permite a comentar em várias linhas ou no meio de uma linha.