Какой метод комментирования объектов и методов JavaScript является предпочтительным?

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

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

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

Попробуйте вставить следующее в файл 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-файлы для использования в больших библиотеках) можно найти на Блог Скотта Гу.

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

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

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

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

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