Workspace Docs

Appearance

JSDoc Annotations

Формат JSDoc-блока ​

Движок ищет JSDoc-блоки (/** ... */), содержащие тег @doc_id. Каждый блок должен содержать:

  • @doc_id <page.fragment> — уникальный идентификатор фрагмента
  • @description или тело блока — текстовое описание в markdown

Пример:

ts
/**
 * @description
 * `App.vue` задаёт основной каркас Builder.
 * Компонент собирает постоянные части экрана.
 * @doc_id system-components.summary
 */

Извлечение фрагментов ​

Извлечение фрагментов сканирует файлы внутри sourceRoot и additionalRoots из doc space config и собирает JSDoc-блоки, объявленные как фрагменты документации. sourceRoot — основной корень приложения; additionalRoots — дополнительные корни (обычно peer-библиотеки вроде libs/bms-libui/src), откуда тянутся и сниппеты, и концептуальные фрагменты о коде, лежащем вне sourceRoot. Расширения берутся из config.supportedSourceExtensions или дефолтного набора .ts, .tsx, .vue. JSDoc-блоки без объявления фрагмента пропускаются. Файлы дедуплицируются по пути, чтобы пересечение корней не давало дублей.

Привязка к исходнику ​

После чтения JSDoc-блока Autodoc сохраняет, из какого файла и с каких строк этот фрагмент был получен.

Когда extractor находит JSDoc-фрагмент, он сохраняет SourceRef: путь к исходному файлу и диапазон строк найденного блока. Эти данные попадают в markdown как DocFragmentSource и дают кнопку src рядом с фрагментом.

Валидация JSDoc-фрагментов ​

JSDoc-блок не просто копируется в markdown: exporter проверяет, что у него есть корректный @doc_id, описание и существующая страница-владелец.

Здесь проверяется владелец: inferFragmentPageId() ищет page id по prefix, а отсутствие владельца превращается в BuildIssue.

Проблемы, найденные при разборе JSDoc-фрагмента, записываются в issues как BuildIssue: дальше diagnostics печатают файл и строки, а ошибки останавливают export на финальном assertNoErrors().

Mentioned In ​