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.
class Circle { /** * Создает экземпляр Circle.
* @constructor * @this {Circle} * @param {number} r - Радиус окружности. */ constructor(r) { /** @private */ this.radius = r;
/** @private */ this.circumference = 2 * Math.PI * r;
/** * Подсчитывает длину окружности
* @deprecated * @this {Circle} * @return {number} Длина окружности. */ calculateCircumference() { return 2 * Math.PI * this.radius;
/** * Возвращает длину окружности, вычисленную заранее.
* @this {Circle} * @return {number} Длина окружности. */ getCircumference() { return this.circumference;
/** * Строковое представление объекта Circle.
* @override * @this {Circle} * @return {string} Информация об объекте Circle. */
toString() { return "A Circle object with radius of " + this.radius + ".";
/** * Создает новый экземпляр Circle по диаметру.
* @param {number} d - Диаметр окружности. * @return {Circle} Новый объект Circle.
* @static */ static fromDiameter(d) { return new Circle(d / 2);
История Самый ранний пример использования комментариев в стиле Javadoc для документирования JavaScript кода приходится на 1999 год и проект Netscape/Mozilla Rhino.
Использование JSDoc Google’s Closure Linter и Closure Compiler Синтаксис 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 , Mozilla Inline Editor использует JSDoc.
См. также Javadoc PhpDocumentor Генератор документации
Примечания
Ссылки JSDoc-toolkit, список тегов Пишем примечания к JavaScript коду для Closure Compiler Пишем полезную JavaScript документацию с помощью JSDoc
Генераторы документации Официальная страница JSDoc 3, содержит учебные пособия и документацию по использованию. Генерирует HTML Подмножество JSDoc3 , генерирующий Markdown файлы
Категория:Свободные генераторы документации Категория:Языки разметки Категория:Инструменты программирования для JavaScript