Каков предпочтительный метод комментирования объектов и методов 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() { ... }

В качестве бонуса, пожалуйста, дайте мне знать, есть ли какие-либо генераторы API для JavaScript, которые могли бы читать "предпочтительный" стиль комментариев.

Ответ 1

Есть 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;
}

Ответ 2

Чем проще, тем лучше, комментарии хороши, используйте их :)

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

Ответ 3

Yahoo предлагает YUIDoc.

Он хорошо документирован, поддерживается Yahoo и является Node.js.

Он также использует много одного и того же синтаксиса, поэтому не так много изменений нужно будет переходить от одного к другому.

Ответ 4

Попробуйте вставить следующее в javascript файл в Visual Studio 08 и поиграть с ним:

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 в изобилии!

Подробнее об этом (в том числе о том, как ссылаться на внешние javascript файлы, для использования в больших библиотеках) можно найти на блог Скотта Гуга.

Ответ 5

Использование тройного комментария в первом примере фактически используется для внешних инструментов документации XML и (в Visual Studio) поддержки intellisense. Его по-прежнему действительный комментарий, но его особый:) Операционный комментарий "оператор" есть // Единственное ограничение состоит в том, что оно для одной строки.

Во втором примере используется компиляция блоков стиля C, которая позволяет комментировать несколько строк или в середине строки.