Quelle est la méthode préférée de commenter les objets javascript & méthodes

Je suis habitué à l'atlas où les privilégiés (de ce que je connais) méthode consiste à utiliser le format xml des commentaires 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 été à la recherche dans d'autres 3ème partie les bibliothèques javascript et je vois une syntaxe du type: 

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

Comme un bonus, s'il vous plaît laissez-moi savoir si il y a une API générateurs de code JavaScript qui pourrait lire le préféré de la commenter style.

InformationsquelleAutor EvilSyn | 2008-09-24
  1. 67

    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;
}
    InformationsquelleAutor Chris MacDonald
  2. 12

    Le plus simple sera le mieux, les commentaires sont bons, les utiliser 🙂

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

    /**
 * 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() {
    //...
}
    • Je suis en désaccord sur le compte de "la plus simple sera le mieux", vous devez installer un commentaires add-on dans votre IDE de générer automatiquement le deuxième style, parce que c'est plus utile
    InformationsquelleAutor molokoloco
  3. 7

    Yahoo offre YUIDoc.

    C'est bien documenté, appuyé par Yahoo, et est un Node.js app.

    Il utilise aussi beaucoup de la même syntaxe, donc pas beaucoup de changements devront être faits pour aller de l'un à l'autre.

    InformationsquelleAutor Chris MacDonald
  4. 2

    Essayer de coller le texte suivant dans un fichier javascript dans Visual Studio 08 et de jouer avec elle:

    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'infos à ce sujet (y compris la façon de référence javascript externe-files, pour une utilisation dans de grandes bibliothèques) peut être trouvé sur Scott Gu blog.

    InformationsquelleAutor cllpse
  5. 1

    L'utilisation de la triple commentaire dans le premier exemple est effectivement utilisé pour XML externe des outils de documentation et (dans Visual Studio) intellisense de soutien. Il y a encore un commentaire valide, mais sa particularité 🙂 Le actuall commentaire "opérateur" est //
    La seule limitation il y a, c'est pour une seule ligne.

    Le deuxième exemple utilise C bloc de style de commentaire qui permet de faire des commentaires sur plusieurs lignes ou dans le milieu d'une ligne.

    • Righto - et j'ai lu récemment que son être éliminé (au moins pour les JS de soutien) c'est pour ça que je posais la question. Merci!
    InformationsquelleAutor Jim Burger