JSDoc

Эта статья требует дополнительных ссылок для проверки . Пожалуйста, помогите улучшить эту статью , добавив цитаты из надежных источников . Материал, не полученный от источника, может быть оспорен и удален. Поиск источников:  «JSDoc»  -  новости  · газеты  · книги  · ученый  · JSTOR ( январь 2013 г. ) ( Узнайте, как и когда удалить этот шаблон сообщения )

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

История [ править ]

Ранний пример использования синтаксиса, подобного Javadoc, для документирования JavaScript был выпущен в 1999 году в рамках проекта Netscape / Mozilla Rhino , исполняющей системы JavaScript, написанной на Java . Он включал игрушечный 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 Code . ^[3] К 2011 году он реорганизовал систему в JSDoc 3.0 и разместил результат на GitHub . Теперь он работаетNode.js . ^[4]

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

Теги JSDoc [ править ]

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

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

Пример [ править ]

/ ** @class Circle, представляющий круг. * / class  Circle  { / ** * Создает экземпляр Circle. * * @author: moi * @param {number} r Желаемый радиус круга. * /  constructor ( r )  {  / ** @private * /  this . радиус  =  r  / ** @private * /  this . окружность  =  2  *  Мат . PI  *  r  } / **  * Создает новый круг из диаметра.  *  * @param {number} d Желаемый диаметр круга.  * @return {Circle} Новый объект Circle.  * /  static  fromDiameter ( d )  {  вернуть  новый  круг ( d  /  2 )  } / **  * Вычисляет длину окружности круга.  *  * @deprecated с 1.1.0; вместо этого используйте getCircumference  * @return {number} Длина окружности круга.  * /  calculateCircumference ()  {  return  2  *  Math . Пи  *  это . радиус  } / **  * Возвращает предварительно вычисленную длину окружности круга.  *  * @return {number} Длина окружности круга.  * @since 1.1.0  * /  getCircumference ()  {  вернуть  это . окружность  } / **  * Найдите строковое представление круга.  *  * @override  * @return {строка} Удобочитаемое представление этого Круга.  * /  toString ()  {  return  `[Объект Circle с радиусом $ { this . радиус } .] `  } }/ ** * Печатает круг. * * @param {Circle} circle * / function  printCircle ( circle )  {    / ** @this {Circle} * /    function  bound ()  {  console . log ( this )  }  привязан . применить ( круг ) }

Обратите внимание, что теги @classи @constructorна самом деле можно опустить: ECMASyntax достаточно, чтобы сделать их идентичными, и JSDoc использует это. ^{[5] также} @override может быть выведено автоматически. ^[6]

JSDoc используется [ править ]

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

См. Также [ править ]

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

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

Внешние ссылки [ править ]

• Официальный веб-сайт JSDoc , для руководств и документации по использованию
• Официальный JSDoc Github , актуальный код
• «Аннотирование JavaScript для компилятора закрытия» , документация по инструментам закрытия, веб-сайт разработчика Google