deno doc, генератор документации

deno doc [OPTIONS] [source_file]...

deno doc ./path/to/module.ts

deno doc --html --name="My library" ./path/to/module.ts

deno doc --lint ./path/to/module.ts

deno doc ./path/to/module.ts MyClass.someField

deno doc

deno doc --filter Deno.Listener

Параметры управления зависимостями

--import-map

Загрузить файл карты импорта из локального файла или удаленной URL-адреса.

--lock

Проверить указанный файл блокировки. (Если значение не указано, используется по умолчанию "./deno.lock").

--no-lock

Отключить автоматическое обнаружение файла блокировки.

--no-npm

Не разрешать модули npm.

--no-remote

Не разрешать удаленные модули.

--reload

Короткая команда: -r

Перезагрузить кэш исходного кода (перекомпилировать TypeScript) без значения Перезагрузить всё jsr:@std/http/file-server,jsr:@std/assert/assert-equals Перезагружает конкретные модули npm: Перезагрузить все модули npm npm:chalk Перезагрузить конкретный модуль npm.

Параметры

--allow-import

Короткая команда: -I

Разрешить импорт из удаленных хостов. Можно указать разрешенные IP-адреса и имена хостов, при необходимости с портами. Значение по умолчанию: deno.land:443,jsr.io:443,esm.sh:443,cdn.jsdelivr.net:443,raw.githubusercontent.com:443,user.githubusercontent.com:443.

Параметры документации

--category-docs

Путь к JSON-файлу, индексированному по категориям, и необязательному значению документа Markdown.

--default-symbol-map

Использует предоставленное отображение стандартного имени на желаемое имя для блоков использования.

--filter

Путь к символу через точку.

--html

Вывести документацию в формате HTML.

--json

Вывести документацию в формате JSON.

--lint

Вывести диагностические сообщения документации.

--name

Имя, которое будет использоваться в документации (например, для навигационной цепочки).

--output

Директория для вывода HTML-документации.

--private

Вывести документацию для частных элементов.

--strip-trailing-html

Удалить окончание .html из различных ссылок. Файлы всё равно будут генерироваться с расширением .html.

--symbol-redirect-map

Путь к JSON-файлу, индексированному по файлам, с внутренней картой символа и внешней ссылки.

Примеры

deno doc за которым следует список одного или нескольких исходных файлов, отобразит документацию JSDoc для каждого из экспортированных членов модуля.

Например, если у вас есть файл add.ts со следующим содержимым:

/**
 * Adds x and y.
 * @param {number} x
 * @param {number} y
 * @returns {number} Sum of x and y
 */
export function add(x: number, y: number): number {
  return x + y;
}

Запустив команду Deno doc , выведется JSDoc-комментарий функции в stdout:

deno doc add.ts
function add(x: number, y: number): number
  Adds x and y. @param {number} x @param {number} y @returns {number} Sum of x and y

Проверка кода

Вы можете использовать --lint флаг для проверки проблем в вашей документации во время её генерации. deno doc выявит три вида проблем:

1. Ошибка для экспортированного типа из корневого модуля, ссылающегося на неэкспортированный тип.
   • Обеспечивает, что потребители API имеют доступ ко всем типам, которые использует API. Это можно подавить, экспортировав тип из корневого модуля (одного из файлов, указанных для deno doc в командной строке) или пометив тип меткой @internal jsdoc.
2. Ошибка отсутствия типа возвращаемого значения или типа свойства в общедоступном типе.
   • Обеспечивает, что deno doc отображает тип возвращаемого значения/свойства и помогает улучшить производительность проверки типов.
3. Ошибка отсутствия JS-комментария к общедоступному типу.
   • Обеспечивает документирование кода. Может быть подавлена добавлением JSDoc-комментария или меткой @ignore jsdoc, чтобы исключить его из документации. В качестве альтернативы, добавьте метку @internal , чтобы сохранить его в документации, но обозначить как внутренний.

Например:

interface Person {
  name: string;
  // ...
}

export function getName(person: Person) {
  return person.name;
}

$ deno doc --lint mod.ts
Type 'getName' references type 'Person' which is not exported from a root module.
Missing JS documentation comment.
Missing return type.
    at file:///mod.ts:6:1

Эти проверки помогают написать лучшую документацию и ускорить проверку типов в ваших проектах. Если какие-либо проблемы обнаружены, программа завершается с ненулевым кодом выхода, и вывод сообщается в стандартный поток ошибок.

Поддерживаемые теги JSDoc

Deno реализует большой набор тегов JSDoc, а также дополнительные теги, которые не определены в спецификации JSDoc. Поддерживаются следующие теги:

• constructor/class: отмечает функцию как конструктор.
• ignore: игнорирует символ для включения в вывод.
• internal: отмечает символ для внутреннего использования. В генераторе HTML символ не будет включён в список, но он по-прежнему будет сгенерирован и доступен, если к нему ссылается не внутренний символ.
• public: рассматривает символ как общедоступный API. Эквивалентно ключевому слову TypeScript public.
• private: рассматривает символ как закрытый API. Эквивалентно ключевому слову TypeScript private.
• protected: рассматривает свойство или метод как защищённый API. Эквивалентно ключевому слову TypeScript protected.
• readonly: отмечает символ как неизменяемый, то есть его нельзя перезаписать.
• experimental: отмечает символ как экспериментальный, что означает, что API может измениться или быть удалён, или поведение не определено чётко.
• deprecated: отмечает символ как устаревший, что означает, что он больше не поддерживается и может быть удалён в будущей версии.
• module: этот тег можно определить в верхнем JSDoc-комментарии, который будет рассматривать этот комментарий как относящийся к файлу, а не последующему символу.
• category/group: отмечает символ как относящийся к определённой категории/группе. Это полезно для группировки различных символов вместе.
• see: определяет внешнюю ссылку, связанную с символом.
• example: определяет пример для символа.
• tags: определяет дополнительные пользовательские метки для символа через список, разделённый запятыми.
• since: определяет, с какого момента символ доступен.
• callback: определяет обратный вызов.
• template/typeparam/typeParam: определяет обратный вызов.
• prop/property: определяет свойство символа.
• typedef: определяет тип.
• param/arg/argument: определяет параметр функции.
• return/returns: определяет тип возвращаемого значения и/или комментарий функции.
• throws/exception: определяет, что функция выбрасывает при вызове.
• enum: определяет объект как перечисление.
• extends/augments: определяет тип, который функция расширяет.
• this: определяет, к чему относится ключевое слово this в функции.
• type: определяет тип символа.
• default: определяет значение по умолчанию для переменной, свойства или поля.

Вывод в HTML

Используйте флаг --html для генерации статического сайта с документацией.

$ deno doc --html --name="My library" ./mod.ts

$ deno doc --html --name="My library" --output=./documentation/ ./mod.ts

$ deno doc --html --name="My library" ./sub1/mod.ts ./sub2/mod.ts

Сгенерированная документация — это статический сайт с несколькими страницами, который можно развернуть на любом хостинге статических сайтов.

На сгенерированном сайте включён поиск на стороне клиента, но он недоступен, если в браузере отключён JavaScript.

Вывод в JSON

Используйте флаг --json для вывода документации в формате JSON. Этот формат JSON используется веб-сайтом deno doc для генерации документации модуля.