deno doc

Примеры

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

Документирование пакета npm или JSR

Начиная с Deno 2.8, deno doc принимает спецификаторы npm: и jsr: и загружает опубликованные типы пакета перед созданием документации. Это удобно для изучения API стороннего пакета из терминала без клонирования репозитория:

deno doc npm:code-block-writer
deno doc jsr:@std/path

Вы можете указать конкретную версию, как и для любого другого спецификатора Deno (npm:zod@4), а также объединить спецификатор с --html или --json, чтобы получить те же форматы вывода, что и для локальных файлов.

Линтинг

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

1. Ошибка: экспортированный тип корневого модуля ссылается на неэкспортированный тип.
   • Гарантирует, что потребители API имеют доступ ко всем типам, используемым API. Эту проверку можно отключить, экспортировав тип из корневого модуля (одного из файлов, указанных для deno doc в командной строке) или пометив тип тегом JSDoc @internal.
2. Ошибка: у общедоступного типа не указан тип возвращаемого значения или свойства.
   • Это позволяет deno doc отображать тип возвращаемого значения или свойства и повышает производительность проверки типов.
3. Ошибка: у общедоступного типа отсутствует комментарий JS Doc.
   • Гарантирует, что код документирован. Эту проверку можно отключить, добавив комментарий JSDoc или тег JSDoc @ignore, чтобы исключить элемент из документации. Также можно добавить тег @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, а ориентируется на разумные стандарты и возможности, предоставляемые широко используемыми инструментами и экосистемами в этой области, такими как TSDoc и TypeDoc.

В местах со свободным текстом, например в основном описании комментария JSDoc или описании параметра, можно использовать Markdown.

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

Поддерживаются следующие теги — некоторые из тегов, используемых и описанных в JSDoc, TSDoc и TypeDoc:

• 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: задаёт пример для символа. В отличие от JSDoc, примеры кода нужно заключать в блоки кода из трёх обратных кавычек (в стиле Markdown), что соответствует скорее TSDoc, чем JSDoc.
• tags: задаёт дополнительные пользовательские метки для символа в виде списка, разделённого запятыми.
• since: указывает, с какого момента символ доступен.
• callback: задаёт функцию обратного вызова.
• template/typeparam/typeParam: задают параметр обобщённого типа.
• prop/property: задают свойство символа.
• typedef: задаёт тип.
• param/arg/argument: задают параметр функции.
• return/returns: задают тип возвращаемого значения функции и/или комментарий к нему.
• throws/exception: описывают ошибки, которые может выбрасывать функция при вызове.
• enum: задаёт объект как перечисление.
• extends/augments: задают тип, от которого наследуется функция.
• this: определяет, на что ссылается ключевое слово this в функции.
• type: задаёт тип символа.
• default: задаёт значение по умолчанию для переменной, свойства или поля.

Встроенные ссылки

Встроенные ссылки позволяют задавать ссылки на другие части страницы, другие символы или модули. Помимо поддержки ссылок в стиле Markdown, поддерживаются также встроенные ссылки в стиле JSDoc.

Например, можно написать {@link https://docs.deno.com}; результатом будет 'https://docs.deno.com'. Также можно использовать {@linkcode https://docs.deno.com}, чтобы отображать текст моноширинным шрифтом; результат будет выглядеть примерно так: 'https://docs.deno.com'.

Также можно указать вместо ссылки собственную метку с помощью {@link https://docs.deno.com | Deno Docs}: текст после | будет отображаться вместо ссылки. В предыдущем примере результатом будет 'Deno Docs'.

В описаниях можно добавлять встроенные ссылки на другие символы с помощью {@link MySymbol}.

Для ссылок на модули действует тот же принцип, но используется синтаксис {@link [myModule]}. Также можно ссылаться на символы в другом модуле с помощью {@link [myModule].mysymbol}.

Вывод в формате 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 для создания документации модулей.

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