JSDoc | это... Что такое JSDoc? (original) (raw)

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

Теги JSDoc

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

Тег	Описание
@author	Имя разработчика
@constructor	Маркирует функцию как конструктор
@deprecated	Маркирует метод устаревшим и не рекомендуемым
@exception	Синоним для @throws
@param	Описывает аргумент функции; можно указать тип, задав его в фигурных скобках
@private	Означает, что метод приватный
@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. */ 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 Rhino.

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

Google’s Closure Linter и Closure Compiler [1]
Синтаксис JSDoc был описан в книге издательства Apress Foundations of Ajax ISBN 1-59059-582-3.
IntelliJ IDEA и RubyMine понимают синтаксис JSDoc.
Для Eclipse IDE существуют плагины, реализующие синтаксис JSDoc. Редактор Aptana Studio, основанный на Eclipse, поддерживает ScriptDoc и включает некоторые файлы на JavaScript, откомментированные в ScriptDoc.
Mozile, Mozilla Inline Editor использует JSDoc.

См. также

Ссылки

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

JSDoc — написан на Perl
JsDoc Toolkit — написан на JavaScript