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

StackOverflow https://stackoverflow.com/questions/127095

  •  02-07-2019
  •  | 
  •  

Вопрос

Я привык к атласу, где предпочтительным (насколько я знаю) методом является использование комментариев 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, которые могут читать «предпочтительный» стиль комментариев.

Это было полезно?

Решение

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

Другие советы

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

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

Yahoo предлагает ЮИДок.

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

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

Попробуйте вставить следующее в файл 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);
};

Интеллисенс в изобилии!

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

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

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

Лицензировано под: CC-BY-SA с атрибуция
Не связан с StackOverflow
scroll top