$ show denoland/deno_doc
This repository is a Rust library (and optional CLI tool) that generates documentation for JavaScript and TypeScript modules. It parses source code using `deno_graph` and `deno_ast`, extracts documentation nodes (functions, classes, interfaces, enums, variables, type aliases, namespaces) along with JSDoc comments, and produces output in multiple formats: JSON for programmatic consumption, plain text for CLI display, static HTML pages with search, dark mode, and breadcrumbs, and structured diffs between two versions of an API. The HTML generation uses Handlebars templates and Tailwind CSS, and includes a client-side search index built with Fuse.js. The crate is used by the `deno doc` command and is published as `@deno/doc` for the JavaScript ecosystem via WASM. Its architecture is modular: a parsing layer resolves source files into a documentation graph, and separate output modules handle text, JSON, HTML, and diff rendering. The diff engine includes rename detection and change heuristics. The project is well-tested with a large suite of snapshot and specification tests covering a wide range of TypeScript features.
The LLM identified 4 files worth highlighting for reuse:
Implements support for `// deno-doc-ignore` and `// deno-doc-ignore-file` comment directives that allow hiding specific lines or entire files from documentation. The logic parses comment lines before or after a code construct and applies ignore rules based on optional codes (e.g., 'no-jsdoc'). This is a self-contained, well-structured pattern that could be reused in any documentation generator or linting tool to handle per-line or per-file suppression directives.
Processes code blocks in JSDoc `@example` tags to support hidden lines (lines starting with `# `, similar to rustdoc). It strips the `#` prefix and removes those lines before rendering, allowing examples to show only explanatory code while keeping boilerplate hidden. This is an isolated utility function with clear input/output contracts, easily extractable for any documentation tool that renders code examples.
Provides a generic partitioning algorithm that takes a list of documentation nodes (symbols) and groups them by kind (functions, classes, etc.), while flattening namespaces and sorting symbols. It also collects module-level documentation and handles references. The logic is decoupled from the rendering layer and uses a configurable `SymbolTransformer` trait. This pattern is reusable for any tool that needs to categorize and order a flat list of API symbols into a hierarchical display.
Implements the core diff engine that compares two parsed documentation outputs (`ParseOutput`). It computes per-module and per-symbol changes (added, removed, modified) with detailed declaration-level diffs. It includes rename detection using `RenameCandidate` traits with similarity heuristics (small vs large changes) and tracks changes in parameters, type parameters, JSDoc, and decorators. While coupled to the crate's data types, the pattern of structured API diffing with rename detection is a well-crafted, non-trivial component that could inspire similar engines for other languages or schemas.