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.
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 Архивная копия от 6 октября 2018 на Wayback Machine, Mozilla Inline Editor использует JSDoc.
См. также
Примечания
Ссылки
Генераторы документации
- Официальная страница JSDoc 3, содержит учебные пособия и документацию по использованию. Генерирует HTML
- Подмножество JSDoc3 Архивная копия от 16 октября 2014 на Wayback Machine, генерирующий Markdown файлы
This article is issued from Wikipedia. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.