Was ist die bevorzugte Methode JavaScript-Objekte und Methoden der Kommentierung [geschlossen]

Question

Ich bin zu Atlas verwendet, in denen die bevorzugten (von dem, was ich weiß) Methode ist xml Anmerkungen 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) { ... }

Vor kurzem habe ich gesucht, in anderen 3rd-Party-JavaScript-Bibliotheken und ich Syntax sehen wie:

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

Als Bonus Sie mich bitte, wenn es irgendwelche API-Generatoren für JavaScript, die die ‚bevorzugte‘ Kommentierung Stil lesen konnte.

Answer 1

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

Answer 2

Je einfacher, desto besser, Kommentare sind gut, sie verwenden:)

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

Answer 3

Yahoo bietet YUIDoc .

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

Es verwendet auch eine Menge von der gleichen Syntax, so würde nicht viele Änderungen müssen von einem zum anderen zu gehen, gemacht werden.

Answer 4

Versuchen Sie Folgendes in eine JavaScript-Datei in Visual Studio 08 und spielen, um mit ihm einfügen:

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 zu diesem (einschließlich, wie externen Javascript-Dateien zu verweisen, für den Einsatz in großen Bibliotheken) auf Scott Gu Blog .

Answer 5

Die Verwendung des Triple-Kommentars im ersten Beispiel wird für externe XML-Dokumentations-Tools und (in Visual Studio) Intellisense Unterstützung tatsächlich verwendet wird. Es ist immer noch ein gültiger Kommentar, aber sein besonderer :) Der actuall Kommentar ‚Betreiber‘ ist // Die einzige Einschränkung ist, dass sein für eine einzelne Zeile.

Das zweite Beispiel verwendet C-Stil Block zu kommentieren, die zur Kommentierung über mehrere Zeilen oder in der Mitte einer Zeile ermöglicht.