Interested Article - 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 .

Использование 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.
  • Для существуют плагины, реализующие синтаксис JSDoc. Редактор Aptana Studio , основанный на Eclipse, поддерживает ScriptDoc и включает некоторые файлы на JavaScript, откомментированные в ScriptDoc.
  • от 6 октября 2018 на Wayback Machine , Mozilla Inline Editor использует JSDoc.

См. также

Примечания

Ссылки

Генераторы документации

  • , содержит учебные пособия и документацию по использованию. Генерирует HTML
  • от 16 октября 2014 на Wayback Machine , генерирующий Markdown файлы
Источник —

Same as JSDoc