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
4.1 KiB
Raw
/**
* Members a declaration inherits.
*
* A page that lists only what a class writes itself is misleading:
* `GrowableArray` reads as though it has no `map`, when `map` is the
* whole reason it implements `Iterable`. So each declaration's
* supertypes are followed and their members copied in, marked with the
* declaration they come from, and a consumer decides whether to show
* them.
*
* This runs after every module is documented and its re-exports
* resolved, because a supertype is usually declared in another module
* and may not have been walked when its subtype was.
*/
import { Set } from 'zena:collections';
import {
DocDeclaration, DocMember, DocPackage, TypeRef,
} from './model.zena';
import { PublishedIndex } from './publish.zena';
/**
* How far up a hierarchy to follow.
*
* Depth is small in practice; the cap is what stops a cycle in the
* recorded supertypes from looping rather than reporting.
*/
let MAX_DEPTH = 16;
/** Copies inherited members onto every declaration that has supertypes. */
export function inheritMembers(pkg: DocPackage): void {
let index = new PublishedIndex(pkg);
for (let module in pkg.modules) {
for (let declaration in module.declarations) {
let inherited = new Array<DocMember>(0);
let seenTypes = new Set<String>();
let seenNames = new Set<String>();
for (let member in declaration.members) {
seenNames.add(member.name);
}
collect(declaration, index, inherited, seenTypes, seenNames, 0);
for (let member in inherited) {
declaration.members.push(member);
}
}
}
}
/** Walks one declaration's supertypes, nearest first. */
function collect(
declaration: DocDeclaration,
index: PublishedIndex,
out: GrowableArray<DocMember>,
seenTypes: Set<String>,
seenNames: Set<String>,
depth: i32
): void {
if (depth > MAX_DEPTH) {
return;
}
for (let supertype in supertypesOf(declaration)) {
let target = index.find(supertype);
if (target == null) {
continue;
}
if (seenTypes.has(target.id)) {
continue;
}
seenTypes.add(target.id);
for (let member in target.members) {
// Only what the supertype declares itself. Its own inherited
// copies are skipped and reached by recursing instead, so a
// member is always attributed to the type that declares it and
// the result does not depend on which declaration this pass
// happened to reach first.
if (member.inheritedFrom != null) {
continue;
}
// A member the subtype declares itself wins, and so does the
// nearest supertype that declares it — this walks nearest first.
if (seenNames.has(member.name)) {
continue;
}
seenNames.add(member.name);
out.push(inheritedCopy(member, target));
}
collect(target, index, out, seenTypes, seenNames, depth + 1);
}
}
/** Every id this declaration's supertypes resolve to. */
function supertypesOf(declaration: DocDeclaration): GrowableArray<String> {
let out = new Array<String>(2);
let superClass = declaration.superClass;
if (superClass != null) {
addLinks(out, superClass);
}
for (let one in declaration.interfaces) {
addLinks(out, one);
}
for (let one in declaration.mixins) {
addLinks(out, one);
}
return out;
}
/**
* The declarations a supertype reference names.
*
* The first link is the supertype itself; later ones are its type
* arguments, which are not supertypes — `implements Iterable<T>`
* inherits from `Iterable`, not from `T`.
*/
function addLinks(out: GrowableArray<String>, type: TypeRef): void {
if (type.links.length > 0) {
out.push(type.links[0].id);
}
}
/** A member copied onto a subtype, recording where it comes from. */
function inheritedCopy(member: DocMember, from: DocDeclaration): DocMember {
let copy = new DocMember(member.kind, member.name, member.id, member.anchor,
member.signature);
copy.isStatic = member.isStatic;
copy.isAbstract = member.isAbstract;
copy.mutability = member.mutability;
copy.typeParameters = member.typeParameters;
copy.parameters = member.parameters;
copy.type = member.type;
copy.doc = member.doc;
copy.loc = member.loc;
copy.inheritedFrom = from.id;
return copy;
}
- 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 |
|
|