Quelle est la méthode préférée pour commenter les objets javascript? méthodes [fermé]

Question

Je suis habitué aux atlas où la méthode préférée (d'après ce que je sais) consiste à 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, je me suis intéressé à d'autres bibliothèques javascript tierces et je vois une syntaxe telle que:

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

En prime, veuillez me faire savoir s'il existe des générateurs d'API pour JavaScript capables de lire le style de commentaire "préféré".

Answer 1

Il existe 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

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 générés automatiquement ...

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

Yahoo propose des 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, de sorte qu'il ne devrait pas y avoir beaucoup de changements pour passer de l'un à l'autre.

Answer 4

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, à utiliser dans des bibliothèques volumineuses) sont disponibles sur Le blog de Scott Gu .

Answer 5

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), le support intellisense. C'est toujours un commentaire valide, mais c'est spécial :) Le commentaire exact "opérateur" est // La seule limitation est que cela concerne une seule ligne.

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