doc

js/commands/doc.ts

fino:commands/doc — reusable API documentation command task.

Builds the fino doc command tree and contains the source parser, Markdown and HTML renderers, search database generation, and doc-test runner used by that command. The build path parses commented TypeScript and JavaScript sources (plus Markdown guide pages), extracts module and symbol doc comments, resolves supported re-exports, and writes generated documentation under docs/: one Markdown and/or HTML page per module and guide, an api.json snapshot, and a SQLite index (docs.db) with full-text search. Stale generated pages are pruned after each build, and per-file parse results are cached in the index keyed by size and mtime so unchanged files are not re-parsed.

show and search query the generated index, transparently refreshing it from the recorded input roots when a lookup misses. test extracts fenced ts/js code blocks from doc comments and executes each one in an isolated realm: blocks tagged no_run or ignore are skipped, and blocks tagged throws must reject.

Use this module when another interface needs to mount the built-in docs workflow as a Task. Helper functions remain module-private because they assume Fino command context, runtime filesystem APIs, and documentation output conventions.

Example

import docCommand from 'fino:commands/doc';

await docCommand.parse([
  'build',
  '--format',
  'markdown',
  'js/internal/stream.ts',
]);

Interfaces

interface DocTag {

Properties

name: string
value: string

interface DocBlockItem {

Properties

kind: string
text?: string
lang?: string
meta?: string
code?: string
hiddenCode?: string
name?: string
description?: string

interface DocBlock {

Properties

text: string
tags: DocTag[]
blocks?: DocBlockItem[]

interface Location {

Properties

line: number
column: number

interface DocMember {

Properties

id?: string
name: string
kind: string
signature: string
signatures?: string[]
aliases?: string[]
reExport?: ReExportDoc
doc: DocBlock
location: Location

interface DocExport extends DocMember {

Properties

members: DocMember[]

interface ReExportDoc {

Properties

mode: 'inline' | 'link'
sourceModule: string
sourceName: string
sourceId?: string

interface ModuleDoc {

Properties

id?: string
path: string
name: string
sourceModule?: string
outputPath?: string
doc: DocBlock
exports: DocExport[]

interface GuideDoc {

Properties

id: string
path: string
href: string
title: string
summary: string
text: string
weight?: number

interface ApiDoc {

Properties

schemaVersion?: number
input?: DocInputMetadata
modules: ModuleDoc[]
guides?: GuideDoc[]

interface HtmlMember {

Properties

id: string
name: string
kind: string
titleHtml: string
overloadsHtml: string
docHtml: string

interface HtmlExport extends HtmlMember {

Properties

memberGroups: HtmlGroup < HtmlMember > []
hasMemberGroups: boolean

interface HtmlGroup<T> {

Properties

title: string
items: T[]

interface HtmlModule {

Properties

name: string
id: string
title: string
path: string
href: string
exportCount: number
summary: string
summaryHtml: string
docHtml: string
symbolIndexHtml: string
hasSymbolIndex: boolean
groups: HtmlGroup < HtmlExport > []
hasGroups: boolean

interface HtmlGuide {

Properties

id: string
title: string
path: string
href: string
html: string
pageIndexHtml: string
hasPageIndex: boolean

interface DocInputMetadata {

Properties

files: string[]
types: string[]

Constants

const command

The doc command task mounted as fino doc by the root CLI.

Invoking the command without a subcommand runs the build path. Four subcommands are available:

  • build <files...> — generate documentation from source files, directories, or globs. --format selects markdown (default), html, or both; --title overrides the page title otherwise inferred from package.json or Cargo.toml; --types merges additional declaration inputs into the same docs; --include-private also documents @internal and private declarations.
  • show <symbol> — print one documented symbol as Markdown by id or name, with "did you mean" suggestions when nothing matches exactly.
  • search <query...> — full-text search over the generated docs index.
  • test <files...> — extract fenced examples from doc comments and run each one in an isolated realm.

Parser, filesystem, rendering, and doc-test failures propagate as command errors. Throws from build and test if no source files are specified, and from show and search when no prior doc build exists to refresh from.

import doc from 'fino:commands/doc';

await doc.parse(['build', '--format', 'both', 'js/internal/stream.ts']);
await doc.parse(['search', 'Stream']);
await doc.parse(['show', 'stream.Stream']);