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
3.4 KiB
Raw
/**
* Where each declaration is published.
*
* A type reference resolves through the symbol, so it names the module
* that *declares* a type — often a package-private file with no page of
* its own. `zena:simd/shapes.zena#F32x4` is documented as
* `zena:simd#F32x4`, and anything following a link has to arrive at the
* page that exists.
*
* Two things create that gap: a re-exported copy, which records the id
* it had where it is declared, and a manifest module whose entry file is
* not `<name>.zena`, which the compiler loads by a path-shaped id.
*/
import {
DocDeclaration, DocMember, DocPackage, DocTypeParam, TypeRef,
} from './model.zena';
/** Resolves the id a link carries to the declaration a reader can open. */
export final class PublishedIndex {
#byId = new Map<String, DocDeclaration>();
#aliases = new Map<String, String>();
new(pkg: DocPackage) {
for (let module in pkg.modules) {
let canonical = module.canonicalId;
for (let declaration in module.declarations) {
this.#byId[declaration.id] = declaration;
let original = declaration.originalId;
if (original != null && !this.#aliases.has(original)) {
this.#aliases[original] = declaration.id;
}
if (canonical != null && canonical != module.id) {
let byPath = `${canonical}#${declaration.name}`;
if (!this.#aliases.has(byPath)) {
this.#aliases[byPath] = declaration.id;
}
}
}
}
}
/** The published id for a link, or the link's own if it has no page. */
idFor(id: String): String {
if (this.#aliases.has(id)) {
return this.#aliases[id];
}
return id;
}
/** The declaration a link names, or null when nothing publishes it. */
find(id: String): DocDeclaration | null {
let published = this.idFor(id);
if (this.#byId.has(published)) {
return this.#byId[published];
}
return null;
}
}
/**
* Rewrites every link to the id of the page that hosts it.
*
* Done to the model rather than on the way out, so that anything
* reading it — the inheritance pass, the serializer, a future consumer
* — sees one set of ids.
*/
export function resolveLinks(pkg: DocPackage): void {
let index = new PublishedIndex(pkg);
for (let module in pkg.modules) {
for (let declaration in module.declarations) {
resolveOne(index, declaration.type);
resolveOne(index, declaration.superClass);
for (let one in declaration.interfaces) {
resolveOne(index, one);
}
for (let one in declaration.mixins) {
resolveOne(index, one);
}
resolveParams(index, declaration.typeParameters);
for (let param in declaration.parameters) {
resolveOne(index, param.type);
}
for (let member in declaration.members) {
resolveMember(index, member);
}
}
}
}
function resolveMember(index: PublishedIndex, member: DocMember): void {
resolveOne(index, member.type);
resolveParams(index, member.typeParameters);
for (let param in member.parameters) {
resolveOne(index, param.type);
}
}
function resolveParams(
index: PublishedIndex,
params: GrowableArray<DocTypeParam>
): void {
for (let param in params) {
resolveOne(index, param.bound);
resolveOne(index, param.defaultType);
}
}
function resolveOne(index: PublishedIndex, type: TypeRef | null): void {
if (type == null) {
return;
}
for (let link in type.links) {
link.id = index.idFor(link.id);
}
}
- 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 |
|
|