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 [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.

См. также[править | править код]

Примечания[править | править код]

Ссылки[править | править код]

Генераторы документации[править | править код]

Источник — https://ru.wikipedia.org/w/index.php?title=JSDoc&oldid=135466548