JSDoc - JSDoc

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

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

История

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

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

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

Теги JSDoc

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

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

Пример

/ ** @class Circle, представляющий круг. * /учебный класс Круг {/** * Создает экземпляр Circle. * * @constructor * @author: moi * @param {number} r Желаемый радиус круга. */  конструктор(р) {    /** @частный */ это.радиус = р    /** @частный */ это.длина окружности = 2 * Математика.ЧИСЛО ПИ * р  }  /**   * Создает новый круг из диаметра.   *   * @param {number} d Желаемый диаметр круга.   * @return {Circle} Новый объект Circle.   */  статический fromDiameter(d) {    возвращаться новый Круг(d / 2)  }  /**   * Вычисляет длину окружности круга.   *   * @deprecated с 1.1.0; вместо этого используйте getCircumference   * @return {number} Длина окружности круга.   */  вычислить окружность() {    возвращаться 2 * Математика.ЧИСЛО ПИ * это.радиус  }  /**   * Возвращает предварительно вычисленную длину окружности круга.   *   * @return {number} Длина окружности круга.   * @since 1.1.0   */  getCircumference() {    возвращаться это.длина окружности  }  /**   * Найдите строковое представление круга.   *   * @override   * @return {строка} Человеческое представление этого Круга.   */  нанизывать() {    возвращаться `[Объект Circle с радиусом ${это.радиус}.]`  }}/** * Печатает круг. * * @param {Circle} круг */функция printCircle(круг) {    / ** @ этот {Круг} * /    функция граница() { консоль.бревно(это) }    граница.подать заявление(круг)}

Обратите внимание, что @учебный класс и @конструктор Фактически, теги могут быть опущены: ECMASyntax достаточно, чтобы сделать их идентичными, и JSDoc использует это.[5] @override могут быть выведены автоматически.[6]

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

  • Закрытие ЛИНТЕР Google и Компилятор закрытия. Последний извлекает информацию о типе для оптимизации своего выходного JavaScript.
  • Машинопись может выполнять проверку типа для файлов JavaScript с аннотациями типа JSDoc.[7] Microsoft определила новый язык TSDoc с расширяемыми тегами.
  • Популярный редактор Возвышенный текст поддерживает JSDoc через плагин DocBlockr или DoxyDoxygen
  • Синтаксис JSDoc подробно описан в книге Apress. Основы Ajax ISBN  1-59059-582-3.
  • IntelliJ IDEA, NetBeans, Код Visual Studio и RubyMine понимать синтаксис JSDoc.
  • На основе Eclipse Аптана Студия поддерживает ScriptDoc.
  • Mozile, встроенный редактор Mozilla использует JSDoc.pm.
  • В Хельма каркас приложения использует JSDoc.
  • Документация SproutCore была создана с использованием JSDoc. [1]
  • Visual Studio, WebStorm и многие другие Интегрированные среды разработки или же Текстовые редакторы предлагать автозавершение кода и другую помощь на основе комментариев JSDoc.
  • Открытый исходный код Атом редактор поддерживает JSDoc через атом-простой-jsdoc плагин.

Смотрите также

Рекомендации

  1. ^ "Пример Rhino: jsdoc.js". GitHub. Проект Mozilla. 6 мая 1999 г.
  2. ^ "JSDoc". SourceForge. Конвертация Git
  3. ^ "jsdoc-toolkit". Код Google. Конвертация Git
  4. ^ а б "JSDoc". GitHub. jsdoc. 4 сентября 2019 г.. Получено 4 сентября 2019.
  5. ^ «Классы ES 2015». Используйте JSDoc.
  6. ^ "@override". Используйте JSDoc.
  7. ^ «Проверка типов файлов JavaScript». Документация по TypeScript.

внешняя ссылка