zenadoc 0.0.2-preview.1
Extracts a Zena package's public API as JSON
zenadoc#
Extracts a Zena package's public API from source and serializes it as JSON: every module the package exports, the declarations in each, their members, signatures, resolved type links, and doc comments.
Usage#
Command Line#
zena doc ./my-package -o api.json # a package with zena-package.json
zena doc ./src # any directory, to stdout
zena doc main.zena # a single file
Library API#
import { documentPackage, DocumentOptions } from 'zenadoc';
import { loadPackage } from 'zenadoc/package';
import { packageToJson } from 'zenadoc/json';
let pkg = await loadPackage('./my-package');
let result = await documentPackage(pkg, new DocumentOptions());
let json = packageToJson(result.docs);
Libraries#
zenadoc/zenadoc/document— compiles and documents a package (documentPackage,DocumentOptions,DocumentResult)zenadoc/package— discovers a package's exported modules fromzena-package.jsonor the filesystem (loadPackage,Package,ModuleSpec)zenadoc/model— API documentation model (DocPackage,DocModule,DocDeclaration,DocMember,TypeRef,TypeLink,DeclarationKind,MemberKind)zenadoc/json— serializes aDocPackageto JSON (packageToJson)zenadoc/extract— walks a parsedModuleAST into aDocModule(extractModule,ExtractOptions)zenadoc/reexports— follows re-exported declarations across modules (resolveReexports,WalkCache)zenadoc/inherit— copies inherited members from supertypes (inheritMembers)zenadoc/links— resolves type references to declaration targets via scope analysis (linkModule,ScopeIndex)zenadoc/publish— rewrites declaration links to their public hosting module (publishLinks)zenadoc/type-text— renders type annotations to text and records declaration spans (renderTypeAnnotation)zenadoc/ids— formats module and declaration anchor IDs (moduleId,anchorFor)
License#
MIT
2.0 KiB
Raw
/**
* Resolving a type reference to the declaration it names.
*
* Scope analysis already records a symbol for every type-reference
* node — it is what the checker resolves a `NamedTypeAnnotation`
* through — so a link is a lookup rather than a second name
* resolution. Going through the symbol is what makes the link exact:
* a type parameter `T` and a class named `T` render identically and
* resolve differently, and an imported name resolves to the module
* that declares it rather than the one that imports it.
*/
import { Node, TypeParameter } from 'compiler/ast';
import { SemanticModel } from 'compiler/semantic-model';
import { Naming } from './ids.zena';
import { TypeLinker } from './type-text.zena';
/** Links type references using one module's semantic model. */
export final class ModelLinker implements TypeLinker {
// Nullable rather than the caller holding a `ModelLinker | null`,
// which cannot be passed where `TypeLinker | null` is expected:
// https://code.rictic.com/justin/zena/issues/476.
#model: SemanticModel | null;
#naming: Naming;
new(model: SemanticModel | null, naming: Naming)
: #model = model, #naming = naming;
idFor(annotation: Node): String | null {
let model = this.#model;
if (model == null) {
return null;
}
// `symbol` is a keyword, hence `found`.
let found = model.resolve(annotation);
if (found == null) {
return null;
}
// Follow imports to whatever finally declares the name.
let target = found.resolveTarget();
let declaration = target.declaration;
if (declaration == null) {
// A builtin: `i32`, `String` before the prelude declares it. There
// is no page to point at.
return null;
}
// A type parameter is scoped to the declaration that introduces it,
// so it names nothing a reader can navigate to.
if (declaration is TypeParameter) {
return null;
}
if (target.name.length == 0) {
return null;
}
return `${this.#naming.idOf(target.modulePath)}#${target.name}`;
}
}
- compiler compiler.zena-lang.pkg.zena-lang.dev 0.0.2-preview.1
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.2-preview.1 | 2026-11-19 |
|
|