JSDoc

Первоначальный выпуск	1999 год ( 1999 )
Последний выпуск	3.6.3 15 июля 2019 г ( 15.07.2019 )
Тип формата	Формат документации по программированию
Содержится	JavaScript Исходные файлы
Расширено с	JavaDoc
Открытый формат ?	Да
Веб-сайт	jsdoc .приложение

JSDoc — это язык разметки, используемый для аннотирования JavaScript исходного кода файлов . Используя комментарии, содержащие JSDoc, программисты могут добавлять документацию, описывающую интерфейс программирования приложения , который они создают. Затем он обрабатывается с помощью различных инструментов для создания документации в доступных форматах, таких как HTML и Rich Text Format . Спецификация JSDoc выпущена под лицензией CC BY-SA 3.0 , а сопутствующий генератор документации и библиотека синтаксического анализатора являются бесплатным программным обеспечением под лицензией Apache License 2.0 .

История

Синтаксис и семантика JSDoc аналогичны схеме Javadoc , которая используется для документирования кода, написанного на Java. поведения JavaScript JSDoc отличается от Javadoc тем, что он предназначен для обработки динамического .

Ранний пример использования синтаксиса, подобного Javadoc, для документирования JavaScript, был выпущен в 1999 году вместе с Netscape / Mozilla проектом Rhino , системой времени выполнения JavaScript, написанной на Java . Он включал игрушечный HTML-генератор JSDoc версии до 1.3 в качестве примера возможностей JavaScript.

Все основные поколения «JSDoc» возглавлял Микмат (Майкл Мэтьюз). В 2001 году он начал с JSDoc.pm, простой системы, написанной на Perl . Позже при участии канадского программиста Габриэля Рида. Он был размещен на SourceForge в репозитории CVS . К JSDoc 1.0 (2007) он переписал систему на JavaScript (опять же для Rhino), а после ряда расширений JSDoc 2.0 (2008) получил название «jsdoc-toolkit». Выпущенный под лицензией MIT , он размещался в репозитории Subversion в Google Code . К 2011 году он провел рефакторинг системы в JSDoc 3.0 и разместил результат на GitHub . он работает на Node.js. Теперь

JSDoc-теги

Некоторые из наиболее популярных тегов аннотаций, используемых в современном JSDoc:

Ярлык	Описание
@author	Имя разработчика
@constructor	Отмечает функцию как конструктор
@deprecated	Отмечает метод как устаревший
@exception	Синоним слова @throws
@exports	Идентифицирует член, экспортируемый модулем.
@param	Документирует параметр метода; индикатор типа данных можно добавить между фигурными скобками
@private	Означает, что участник является частным
@returns	Документирует возвращаемое значение
@return	Синоним слова @returns
@see	Документирует связь с другим объектом
@todo	Документирует то, что отсутствует/открыто
@this	Указывает тип объекта, к которому применяется ключевое слово this ссылается внутри функции.
@throws	Документирует исключение, выданное методом.
@version	Предоставляет номер версии библиотеки.

Пример

/** @class Circle representing a circle. */
class Circle {
  /**
   * Creates an instance of Circle.
   *
   * @author: moi
   * @param {number} r The desired radius of the circle.
   */
  constructor(r) {
    /** @private */ this.radius = r
    /** @private */ this.circumference = 2 * Math.PI * r
  }

  /**
   * Creates a new Circle from a diameter.
   *
   * @param {number} d The desired diameter of the circle.
   * @return {Circle} The new Circle object.
   */
  static fromDiameter(d) {
    return new Circle(d / 2)
  }

  /**
   * Calculates the circumference of the Circle.
   *
   * @deprecated since 1.1.0; use getCircumference instead
   * @return {number} The circumference of the circle.
   */
  calculateCircumference() {
    return 2 * Math.PI * this.radius
  }

  /**
   * Returns the pre-computed circumference of the Circle.
   *
   * @return {number} The circumference of the circle.
   * @since 1.1.0
   */
  getCircumference() {
    return this.circumference
  }

  /**
   * Find a String representation of the Circle.
   *
   * @override
   * @return {string} Human-readable representation of this Circle.
   */
  toString() {
    return `[A Circle object with radius of ${this.radius}.]`
  }
}

/**
 * Prints a circle.
 *
 * @param {Circle} circle
 */
function printCircle(circle) {
    /** @this {Circle} */
    function bound() { console.log(this) }
    bound.apply(circle)
}

Обратите внимание, что @class и @constructor теги на самом деле могут быть опущены: синтаксиса ECMASyntax достаточно, чтобы прояснить их идентичность, и JSDoc использует это. @override также может быть автоматически выведено.

JSDoc используется

• от Google Closure Linter и Closure Compiler . Последний извлекает информацию о типе для оптимизации выходного JavaScript.
• TypeScript может выполнять проверку типов файлов JavaScript с аннотациями типов JSDoc. Microsoft определила новый язык TSDoc с расширяемыми тегами.
• Популярный редактор Sublime Text поддерживает JSDoc через плагин DocBlockr или DoxyDoxygen.
• Синтаксис JSDoc подробно описан в книге Apress « Основы Ajax». ISBN   1-59059-582-3 .
• Различные продукты JetBrains, такие как IntelliJ IDEA и WebStorm, NetBeans , Visual Studio Code и RubyMine , понимают синтаксис JSDoc.
• на базе Eclipse Aptana Studio поддерживает ScriptDoc.
• Mozile. Архивировано 6 октября 2018 г. на Wayback Machine . Встроенный редактор Mozilla использует JSDoc.pm.
• Платформа приложений Helma использует JSDoc.
• Документация SproutCore была создана с использованием JSDoc. [1]
• Visual Studio , WebStorm и многие другие интегрированные среды разработки или текстовые редакторы предлагают завершение кода и другую помощь на основе комментариев JSDoc.
• с открытым исходным кодом Редактор Atom поддерживает JSDoc через плагин Atom-easy-jsdoc .

См. также

• Сравнение генераторов документации
• Инструменты закрытия Google

Внешние ссылки

• Официальный сайт
• jsdoc на GitHub
• «Аннотирование JavaScript для компилятора замыканий» . Разработчик Google . Документация по средствам закрытия.