Was ist die bevorzugte Methode zum Kommentieren von JavaScript-Objekten und -Methoden? [closed]

Ich bin an Atlas gewöhnt, wo die bevorzugte Methode (soweit ich weiß) darin besteht, XML-Kommentare zu verwenden, wie zum Beispiel:

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

Kürzlich habe ich mir andere JavaScript-Bibliotheken von Drittanbietern angesehen und sehe eine Syntax wie:

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

Gibt es als Bonus API-Generatoren für JavaScript, die den „bevorzugten“ Kommentarstil lesen können?

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

Je einfacher desto besser, Kommentare sind gut, benutze sie 🙂

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

Aber für automatisch generierte Dokumente …

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

Yahoo bietet YUIDoc.

Es ist gut dokumentiert, wird von Yahoo unterstützt und ist eine Node.js-App.

Es verwendet auch viele der gleichen Syntax, sodass nicht viele Änderungen vorgenommen werden müssten, um von einem zum anderen zu wechseln.

Die Verwendung des dreifachen Kommentars im ersten Beispiel wird tatsächlich für externe XML-Dokumentationstools und (in Visual Studio) Intellisense-Unterstützung verwendet. Es ist immer noch ein gültiger Kommentar, aber es ist etwas Besonderes 🙂 Der eigentliche Kommentar ‘Operator’ ist // Die einzige Einschränkung besteht darin, dass es sich um eine einzelne Zeile handelt.

Das zweite Beispiel verwendet Blockkommentare im C-Stil, die das Kommentieren über mehrere Zeilen oder in der Mitte einer Zeile ermöglichen.

Versuchen Sie Folgendes in eine Javascript-Datei in Visual Studio 08 einzufügen und damit herumzuspielen:

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 in Hülle und Fülle!

Weitere Informationen dazu (einschließlich der Referenzierung externer Javascript-Dateien zur Verwendung in großen Bibliotheken) finden Sie unter Scott Gus Blog.