web-dev-qa-db-fra.com

Quelle est la méthode préférée pour commenter les objets et méthodes JavaScript

J'ai l'habitude d'atlas où la méthode préférée (d'après ce que je sais) est d'utiliser des commentaires xml tels que:

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

Récemment, j'ai cherché dans d'autres bibliothèques javascript tierces et je vois une syntaxe comme:

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

En prime, faites-moi savoir s'il existe des générateurs d'API pour JavaScript qui pourraient lire le style de commentaire "préféré".

javascriptcomments
49
EvilSyn

Il y a 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;
}
70
Chris MacDonald

Le plus simple sera le mieux, les commentaires sont bons, utilisez-les :)

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

Mais pour les documents autogénérés ...

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

Yahoo propose YUIDoc .

Il est bien documenté, pris en charge par Yahoo et est une application Node.js.

Il utilise également beaucoup de la même syntaxe, donc pas beaucoup de changements devraient être faits pour passer de l'un à l'autre.

7
Chris MacDonald

Essayez de coller ce qui suit dans un fichier javascript dans Visual Studio 08 et jouez avec:

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 à gogo!

Plus d'informations à ce sujet (y compris comment référencer des fichiers javascript externes, pour une utilisation dans de grandes bibliothèques) peuvent être trouvées sur blog de Scott G .

2
cllpse

L'utilisation du triple commentaire dans le premier exemple est en fait utilisée pour les outils de documentation XML externes et (dans Visual Studio) la prise en charge d'intellisense. C'est toujours un commentaire valide, mais c'est spécial :) Le commentaire actuall 'opérateur' est // La seule limitation est que c'est pour une seule ligne.

Le deuxième exemple utilise des commentaires de bloc de style C qui permettent de commenter sur plusieurs lignes ou au milieu d'une ligne.

1
Jim Burger