web-dev-qa-db-ja.com

JavaScriptオブジェクトとメソッドにコメントするための好ましい方法は何ですか

私が知っていることから、好ましい方法は次のようなxmlコメントを使用することです。

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

最近、私は他のサードパーティのjavascriptライブラリを調べていましたが、次のような構文があります：

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

おまけとして、「望ましい」コメントスタイルを読み取ることができるJavaScript用のAPIジェネレータがあるかどうかをお知らせください。

javascriptcomments
49
EvilSyn

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

シンプルなほど良い、コメントは良い、それらを使用:)

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

しかし、自動生成されたドキュメントの場合...

/**
 * 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は YUIDoc を提供しています。

文書化されており、Yahooによってサポートされており、Node.jsアプリです。

また、多くの同じ構文を使用するため、一方から他方に移動するために多くの変更を行う必要はありません。

7
Chris MacDonald

Visual Studio 08のjavascriptファイルに次を貼り付けて、試してみてください。

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

豊富なインテリセンス！

これに関する詳細情報（大規模なライブラリで使用するための外部javascriptファイルの参照方法を含む）は Scott Guのブログ にあります。

2
cllpse

最初の例でのトリプルコメントの使用は、実際には外部XMLドキュメントツールおよび（Visual Studioで）インテリセンスのサポートに使用されます。まだ有効なコメントですが、その特別な:)実際のコメント「演算子」は//唯一の制限は、その単一行に対するものです。

2番目の例では、Cスタイルブロックのコメントを使用します。これにより、複数の行または行の途中でコメントすることができます。

1
Jim Burger