JSDoc является стандартом де-факто для документирования кода JavaScript. По сути, JSDoc - это две вещи:

  1. Синтаксис JSDoc - язык / синтаксис разметки, используемый для аннотирования файлов исходного кода JavaScript. Официальная документация по синтаксису JSDoc находится на сайте http://usejsdoc.org/.
  2. Генератор JSDoc - генератор JS-документации JSDoc3 для JavaScript, использующий синтаксис JSDoc.

Вы можете использовать генератор JSDoc3 для создания HTML-сайтов документации JavaScript API. Весь процесс документации API сложен и требует времени, которое можно потратить на новые функции или улучшения. Мы в APIs World считаем, что это стоит решить. Но это уже тема для другого раза.

Синтаксис JSDoc - это то, что должен изучить каждый разработчик JavaScript. Так что это будет в центре внимания этой серии блогов. Но позвольте перейти к делу на простом примере:

В приведенном выше примере у нас есть простая функция JavaScript isRead, которая принимает единственный параметр book и возвращает , если книга уже прочитана. Более важная часть примера - это комментарий JSDoc над функцией. Давайте изучим это:

  1. Комментарии JSDoc добавляются непосредственно в исходный код. Это упрощает их обслуживание. Кроме того, он позволяет использовать инструменты, которые понимают значение этих комментариев (например, Closure Compiler или TypeScript).
  2. Комментарии JSDoc начинаются со следующей строки: ‘/ **’ и заканчиваются следующей строкой: ‘* /’. Каждая строка комментария JSDoc начинается с ‘*’.
  3. В JSDoc используется концепция тегов. В нашем примере это теги @param и @returns. В JSDoc теги начинаются с символа @ и всегда находятся в начале строки комментария JSDoc. У разных тегов разный синтаксис. В нашем примере тег @param имеет тип строка, имя книга, и описание «. название книги. '. Мы более подробно рассмотрим синтаксис каждого тега в этой серии.
  4. Первая строка комментария JSDoc не начинается с тега, который на самом деле является сокращением тега @description. Это общее описание символа, который вы документируете.
  5. Для ссылок на типы в JSDoc используется синтаксис {type}. Типы могут быть примитивными типами, объектами или даже более сложными типами. Мы рассмотрим это в другом сообщении в блоге.
  6. Еще одно важное замечание: комментарии JSDoc связаны с кодом, который находится сразу под комментарием. В нашем примере комментарий JSDoc явно связан с функцией isRead.

Цель этой серии - показать вам, как документировать ES6 JavaScript с помощью JSDoc. ES6 - новейшая спецификация JavaScript, которая реализована практически во всех современных браузерах. Даже если вам нужно настроить таргетинг на старые браузеры, существуют транспилеры, которые могут преобразовать ваш ES6 JavaScript в ES5 JavaScript. См. Babel, Traceur, Closure Compiler или TypeScript.

На этом мы закончили введение в серию «Как задокументировать ES6 JavaScript API с JSDoc». Увидимся в следующем посте, где мы начнем с документирования некоторых основных элементов JavaScript. Позже мы рассмотрим некоторые более продвинутые концепции JSDoc (типы, область видимости, доступ, пути к именам) и ES6 (модули, классы, стрелочные функции, параметры по умолчанию).