Меню
Главная
Случайная статья
Настройки
|
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
См. также
Примечания
Ссылки
Генераторы документации
|
|