JSDocs — это способ документировать и добавлять информацию в написанный нами код. Эта информация отображается во всплывающей подсказке и облегчает разработчикам использование нашего кода.
JSDocs также является генератором документации API, который сканирует файлы и создает документацию на основе документации JSDocs, добавленной к файлам.
Вы также можете конвертировать JSDocs в TypeScript, что упрощает преобразование из ванильного JavaScript в TypeScript.
Это краткое руководство охватывает все, что вам нужно знать, чтобы применять его в учебе и на работе.
Как работают JSDocs:
Мы добавляем JSDocs в функцию, добавляя блочный комментарий с открывающим тегом (/**) и закрывающим тегом (**/). Любые дополнительные строки между этими начальным и закрывающим тегами содержат звездочку *.
Примечание. Добавляемые документы JSDoc должны располагаться непосредственно над блоком кода, который вы документируете.
В приведенном ниже примере у нас есть функция, которая складывает два числа и возвращает результат. Кроме того, мы добавили простое описание того, что будет делать функция.
Добавленное описание появится во всплывающей подсказке при использовании функции.
Мы добавили JSDoc с описанием. Теперь мы рассмотрим различные типы информации, которые мы могли бы включить.
Параметры (@param):
Мы можем использовать @param для указания параметров функции и их описания.
Кроме того, вы можете указать тип данных параметра с помощью фигурных скобок {}.
Возврат (@returns):
Вы можете добавить описание возврата и тип возврата.
Примечание. Мы не указываем имя параметра, потому что в возврате его нет.
Пример использования (@example):
Тег @example, пожалуй, самый важный тег для добавления в ваш JSDoc. Это позволяет вам добавить пример кода с подсветкой синтаксиса, чтобы показать, как использовать написанный вами код.
Предоставление примера кода ускоряет рабочий процесс, позволяя другим разработчикам узнать, как использовать ваш код.
Устаревший код (@deprecated):
JSDocs @устаревшая документация
Тег @deprecated показывает, что код устарел. Устаревшая функция будет иметь эффект зачеркивания имени функции в автозавершении кода. Вы можете предоставить дополнительную информацию, например, какую функцию замены использовать.
Пользовательские типы (@typedef):
Мы можем использовать тег @typedef для документирования пользовательских типов.
В следующем примере вы увидите, что мы добавляем пользовательский @typedef для документирования объекта Person. Добавление этой информации JSDoc позволяет нам увидеть свойства, доступные для параметра, которые в противном случае не отображались бы.
Реагировать Компоненты:
Мы можем использовать JSDocs для документирования наших компонентов.
Компоненты React используют props. Поэтому нам нужно будет использовать @typedef для создания нового пользовательского типа для нашего объекта props и добавить наши свойства в этот @typedef пользовательский тип.
Примечание. Если вы не используете TypeScript, вы можете использовать better-docs. better-docs сэкономит вам несколько шагов и будет использовать PropTypes для создания документации. В этом руководстве мы не будем использовать `better-docs`.
В приведенном ниже примере мы создали компонент с именем Greeting, который отображает приветственное сообщение пользователю с помощью реквизита name, который мы передаем компоненту.
Реагировать на крючки:
Мы можем документировать наши хуки, чтобы другие разработчики могли получить больше информации о возврате наших хуков.
Создание документации JSDocs:
Мы можем генерировать документацию из JSDocs, которые мы добавили в наш код.
Установка:
Сначала нам нужно установить JSDocs глобально или локально.
Глобальная установка:
npm install -g jsdoc
Локальная установка:
npm install — save-dev jsdoc
Примечание. Если вы устанавливаете JSDocs локально, вам нужно будет запустить его из папки node_modules: ./node_modules/jsdoc/jsdoc.js /src -r. В качестве альтернативы вы можете добавить его как скрипт в свой package.json, например. "jsdocs": "jsdoc /src -r" .
Создание файлов:
После установки JSDocs вы можете запустить следующую команду, чтобы сгенерировать документацию для файла с именем `index.js`.
jsdoc index.js
Запуск JSDocs в одном файле бесполезен. В следующем примере будет рекурсивно запускаться генерация JSDocs для всех файлов в каталоге src:
jsdoc src -r
Просмотр документации:
По умолчанию документация будет выводиться в папку с именем out.
Внутри этой папки вы найдете страницу index.html, которую вы можете открыть с помощью Live Server или аналогичного. Как только он откроется, вы увидите созданную нами документацию.
Закрытие:
JSDocs может вывести ваш код на новый уровень при эффективном использовании.
Я надеюсь, что эта статья окажется полезной и позволит вам добавить финишную полировку, которую вы хотите.
Спасибо за ваше время.
