JSDoc

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

Теги JSDoc

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

Пример

Пример использования 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 Rhino.

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

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