JSDoc

Поделись знанием:
Перейти к: навигация, поиск

JSDoc — генератор документации в HTML-формате из комментариев исходного кода на JavaScript. Синтаксис JSDoc похож на синтаксис Javadoc, который используется для документирования Java кода, но предназначен для работы с языком JavaScript, который является более динамичным, и поэтому JSDoc не совместим с Javadoc. Как и Javadoc, JSDoc позволяет программисту создавать доклеты и теги, которые могут быть выведены в файл, например HTML или RTF.






Теги JSDoc

Хотя этот список не полон, следующие теги активно используются.

Тег Описание
@author Имя разработчика
@constructor Маркирует функцию как конструктор
@deprecated Маркирует метод устаревшим и не рекомендуемым
@exception Синоним для @throws
@param Описывает аргумент функции; можно указать тип, задав его в фигурных скобках
@private Означает, что метод приватный
@return Описывает возвращаемое значение
@returns Синоним return
@see Описывает связь с другим объектом
@this Задает тип объекта, на который указывает ключевое слово «this» внутри функции.
@throws Описывает исключения, выбрасываемые методом
@version Версия библиотеки

Пример

Пример использования JSDoc.

/**
 * Создает экземпляр Circle.
 *
 * @constructor
 * @this  {Circle}
 * @param {number} r - Радиус окружности.
 */
function Circle(r) {
    /** @private */
    this.radius = r;
    
    /** @private */
    this.circumference = 2 * Math.PI * r;
}

/**
 * Создает новый экземпляр Circle по диаметру.
 *
 * @param  {number} d - Диаметр окружности.
 * @return {Circle} Новый объект Circle.
 * 
 * @static
 */
Circle.fromDiameter = function (d) {
    return new Circle(d / 2);
};

/**
 * Подсчитывает длину окружности
 *
 * @deprecated
 * @this   {Circle}
 * @return {number} Длина окружности.
 */
Circle.prototype.calculateCircumference = function () {
    return 2 * Math.PI * this.radius;
};

/**
 * Возвращает длину окружности, вычисленную заранее.
 *
 * @this   {Circle}
 * @return {number} Длина окружности.
 */
Circle.prototype.getCircumference = function () {
    return this.circumference;
};

/**
 * Строковое представление объекта Circle.
 *
 * @override
 * @this   {Circle}
 * @return {string} Информация об объекте Circle.
 */
Circle.prototype.toString = function () {
    return "A Circle object with radius of " + this.radius + ".";
};

История

Самый ранний пример использования комментариев в стиле Javadoc для документирования JavaScript кода приходится на 1999 год и проект Netscape/Mozilla [lxr.mozilla.org/mozilla/source/js/rhino/examples/jsdoc.js Rhino].

Использование JSDoc

  • Google’s Closure Linter и Closure Compiler [code.google.com/closure/utilities/]
  • Синтаксис JSDoc был описан в книге издательства Apress Foundations of Ajax ISBN 1-59059-582-3.
  • Visual Studio, IntelliJ IDEA, PhpStorm, WebStorm и RubyMine понимают синтаксис JSDoc.
  • Для [www.interaktonline.com/Products/Eclipse/JSEclipse/Features/Details/Use+of+JSDoc+and+inline+parameter+comments+to+detect+parameter+type.html?id_ftr=639 Eclipse IDE] существуют плагины, реализующие синтаксис JSDoc. Редактор Aptana Studio, основанный на Eclipse, поддерживает ScriptDoc и включает некоторые файлы на JavaScript, откомментированные в ScriptDoc.
  • [mozile.mozdev.org/0.8/doc/jsdoc/index.html Mozile], Mozilla Inline Editor использует JSDoc.

См. также

Напишите отзыв о статье "JSDoc"

Ссылки

  • [code.google.com/p/jsdoc-toolkit/wiki/TagReference JSDoc-toolkit, список тегов]
  • [code.google.com/closure/compiler/docs/js-for-compiler.html Пишем примечания к JavaScript коду для Closure Compiler]
  • [archive.is/20130102063701/blogs.techrepublic.com.com/programming-and-development/?p=451 Пишем полезную JavaScript документацию с помощью JSDoc]

Генераторы документации

  • [usejsdoc.org Официальная страница JSDoc 3], содержит учебные пособия и документацию по использованию. Генерирует HTML
  • [jsdox.org/ Подмножество JSDoc3], генерирующий Markdown файлы

Отрывок, характеризующий JSDoc

– Да, вот как странно судьба свела нас! – сказал он, прерывая молчание и указывая на Наташу. – Она все ходит за мной.
Княжна Марья слушала и не понимала того, что он говорил. Он, чуткий, нежный князь Андрей, как мог он говорить это при той, которую он любил и которая его любила! Ежели бы он думал жить, то не таким холодно оскорбительным тоном он сказал бы это. Ежели бы он не знал, что умрет, то как же ему не жалко было ее, как он мог при ней говорить это! Одно объяснение только могло быть этому, это то, что ему было все равно, и все равно оттого, что что то другое, важнейшее, было открыто ему.
Разговор был холодный, несвязный и прерывался беспрестанно.
– Мари проехала через Рязань, – сказала Наташа. Князь Андрей не заметил, что она называла его сестру Мари. А Наташа, при нем назвав ее так, в первый раз сама это заметила.
– Ну что же? – сказал он.
– Ей рассказывали, что Москва вся сгорела, совершенно, что будто бы…
Наташа остановилась: нельзя было говорить. Он, очевидно, делал усилия, чтобы слушать, и все таки не мог.
– Да, сгорела, говорят, – сказал он. – Это очень жалко, – и он стал смотреть вперед, пальцами рассеянно расправляя усы.
– А ты встретилась с графом Николаем, Мари? – сказал вдруг князь Андрей, видимо желая сделать им приятное. – Он писал сюда, что ты ему очень полюбилась, – продолжал он просто, спокойно, видимо не в силах понимать всего того сложного значения, которое имели его слова для живых людей. – Ежели бы ты его полюбила тоже, то было бы очень хорошо… чтобы вы женились, – прибавил он несколько скорее, как бы обрадованный словами, которые он долго искал и нашел наконец. Княжна Марья слышала его слова, но они не имели для нее никакого другого значения, кроме того, что они доказывали то, как страшно далек он был теперь от всего живого.
– Что обо мне говорить! – сказала она спокойно и взглянула на Наташу. Наташа, чувствуя на себе ее взгляд, не смотрела на нее. Опять все молчали.
– Andre, ты хоч… – вдруг сказала княжна Марья содрогнувшимся голосом, – ты хочешь видеть Николушку? Он все время вспоминал о тебе.
Князь Андрей чуть заметно улыбнулся в первый раз, но княжна Марья, так знавшая его лицо, с ужасом поняла, что это была улыбка не радости, не нежности к сыну, но тихой, кроткой насмешки над тем, что княжна Марья употребляла, по ее мнению, последнее средство для приведения его в чувства.
– Да, я очень рад Николушке. Он здоров?

Когда привели к князю Андрею Николушку, испуганно смотревшего на отца, но не плакавшего, потому что никто не плакал, князь Андрей поцеловал его и, очевидно, не знал, что говорить с ним.
Когда Николушку уводили, княжна Марья подошла еще раз к брату, поцеловала его и, не в силах удерживаться более, заплакала.
Он пристально посмотрел на нее.
– Ты об Николушке? – сказал он.
Княжна Марья, плача, утвердительно нагнула голову.
– Мари, ты знаешь Еван… – но он вдруг замолчал.
– Что ты говоришь?
– Ничего. Не надо плакать здесь, – сказал он, тем же холодным взглядом глядя на нее.