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
7.8 KiB
Raw
/**
* Rendering types as text, with the spans that name a declaration.
*
* A declaration's own annotation is rendered back to source form: it is
* what the author wrote, and for documentation that beats the checker's
* normalized spelling of the same type. When there is no annotation —
* an inferred `let`, a method with no written return type — the
* checker's type is printed with `typeToString` instead, and carries no
* links, because there is no annotation node to resolve.
*
* Rendering happens once, here, and consumers get text plus offsets
* rather than a type tree they would each have to render. See
* docs/design/zenadoc.md.
*/
import {
TypeAnnotation, NamedTypeAnnotation, UnionTypeAnnotation,
NullableTypeAnnotation, FunctionTypeAnnotation, LiteralTypeAnnotation,
RecordTypeAnnotation, TupleTypeAnnotation, InlineTypeAnnotation,
ThisTypeAnnotation, StringLiteral, NumberLiteral,
BooleanLiteral, NullLiteral, Node,
} from 'compiler/ast';
import { Type, typeToString } from 'compiler/types';
import { TypeLink, TypeRef } from './model.zena';
import { StringBuilder } from 'zena:core';
/**
* Resolves a type-reference node to the id of the declaration it names.
*
* Implemented over the semantic model; null when the name resolves to
* nothing documented — a type parameter, a builtin, a type from a
* package this run is not documenting.
*/
export interface TypeLinker {
idFor(annotation: Node): String | null;
}
/** Accumulates the rendered text and the link spans within it. */
final class Render {
sb = new StringBuilder(48);
links = new Array<TypeLink>(0);
linker: TypeLinker | null;
new(this.linker);
write(s: String): void {
this.sb.append(s);
}
/**
* Writes a name and records the span it occupies, when the linker
* knows what the name refers to.
*/
writeName(name: String, node: Node): void {
let start = this.sb.length;
this.sb.append(name);
let linker = this.linker;
if (linker != null) {
let id = linker.idFor(node);
if (id != null) {
this.links.push(new TypeLink(start, this.sb.length, id));
}
}
}
finish(): TypeRef {
return new TypeRef(this.sb.toString(), this.links);
}
}
/** A type annotation as source text, with links to what it names. */
export function annotationRef(
annotation: TypeAnnotation,
linker: TypeLinker | null = null
): TypeRef {
let out = new Render(linker);
renderAnnotation(out, annotation);
return out.finish();
}
/** A type annotation as source text alone. */
export function annotationText(annotation: TypeAnnotation): String {
return annotationRef(annotation, null).text;
}
function renderAnnotation(out: Render, annotation: TypeAnnotation): void {
match (annotation) {
case NamedTypeAnnotation as named: renderNamed(out, named)
case UnionTypeAnnotation {types}: renderJoined(out, types, ' | ')
case NullableTypeAnnotation {typeAnnotation}:
renderNullable(out, typeAnnotation)
case FunctionTypeAnnotation as fn: renderFunction(out, fn)
case LiteralTypeAnnotation {value}: out.write(literalText(value))
case RecordTypeAnnotation as record: renderRecord(out, record)
case TupleTypeAnnotation {elementTypes, spreadIndices}: {
out.write('(');
var i = 0;
for (let element in elementTypes) {
if (i > 0) {
out.write(', ');
}
if (spreadIndices != null && spreadIndices.contains(i)) {
out.write('...');
}
renderAnnotation(out, element);
i += 1;
}
out.write(')');
}
case InlineTypeAnnotation {typeAnnotation, ifPossible}: {
out.write(if (ifPossible) 'inline? ' else 'inline ');
renderAnnotation(out, typeAnnotation);
}
case ThisTypeAnnotation {}: out.write('this')
}
}
function renderNamed(out: Render, named: NamedTypeAnnotation): void {
// The name is what a link points at; the type arguments carry their
// own, so `Map<String, T>` links `Map` and `String` separately.
out.writeName(named.name, named);
let args = named.typeArguments;
if (args == null || args.length == 0) {
return;
}
out.write('<');
renderJoined(out, args, ', ');
out.write('>');
}
/**
* `T?`, parenthesized when the inner type would otherwise bind wrong:
* `A | B` under a `?` has to read as `(A | B)?`.
*/
function renderNullable(out: Render, inner: TypeAnnotation): void {
let needsParens = match (inner) {
case UnionTypeAnnotation {}: true
case FunctionTypeAnnotation {}: true
case InlineTypeAnnotation {}: true
case _: false
};
if (needsParens) {
out.write('(');
}
renderAnnotation(out, inner);
if (needsParens) {
out.write(')');
}
out.write('?');
}
function renderFunction(out: Render, fn: FunctionTypeAnnotation): void {
out.write('(');
var i = 0;
while (i < fn.params.length) {
if (i > 0) {
out.write(', ');
}
if (i < fn.paramNames.length && fn.paramNames[i].length > 0) {
out.write(fn.paramNames[i]);
out.write(': ');
}
renderAnnotation(out, fn.params[i]);
i += 1;
}
out.write(') => ');
renderAnnotation(out, fn.returnType);
}
function renderRecord(out: Render, record: RecordTypeAnnotation): void {
out.write('{');
let spreads = record.spreads;
var written = 0;
var si = 0;
for (let prop in record.properties) {
// Spreads render where they were written, by source position.
if (spreads != null) {
while (si < spreads.length && startsBefore(spreads[si], prop)) {
if (written > 0) {
out.write(', ');
}
out.write('...');
renderAnnotation(out, spreads[si]);
written += 1;
si += 1;
}
}
if (written > 0) {
out.write(', ');
}
out.write(prop.name.name);
if (prop.optional) {
out.write('?');
}
out.write(': ');
renderAnnotation(out, prop.typeAnnotation);
written += 1;
}
if (spreads != null) {
while (si < spreads.length) {
if (written > 0) {
out.write(', ');
}
out.write('...');
renderAnnotation(out, spreads[si]);
written += 1;
si += 1;
}
}
if (record.isExistential) {
if (written > 0) {
out.write(', ');
}
out.write('...');
}
out.write('}');
}
/** Whether `a` starts before `b` in the source; false when either has no location. */
function startsBefore(a: Node, b: Node): boolean {
let la = a.loc;
let lb = b.loc;
return la != null && lb != null && la.start < lb.start;
}
function renderJoined(
out: Render,
annotations: Array<TypeAnnotation>,
separator: String
): void {
var i = 0;
while (i < annotations.length) {
if (i > 0) {
out.write(separator);
}
renderAnnotation(out, annotations[i]);
i += 1;
}
}
function literalText(value: Node): String {
return match (value) {
case StringLiteral as s: `'${s.value}'`
case NumberLiteral as n: n.raw
case BooleanLiteral as b: if (b.value) { 'true' } else { 'false' }
case NullLiteral {}: 'null'
case _: '?'
};
}
/** A `TypeRef` for an annotation, or null when there is none. */
export function refFor(
annotation: TypeAnnotation | null,
linker: TypeLinker | null = null
): TypeRef | null {
if (annotation == null) {
return null;
}
return annotationRef(annotation, linker);
}
/**
* A `TypeRef` for an annotation, falling back to a checked type.
*
* The annotation wins when there is one: `let x: Iterable<i32> = …`
* documents as `Iterable<i32>` even where the checker's type for the
* initializer is narrower. A type with no annotation has no node to
* resolve, so it carries no links.
*/
export function refForOrType(
annotation: TypeAnnotation | null,
type: Type | null,
linker: TypeLinker | null = null
): TypeRef | null {
if (annotation != null) {
return annotationRef(annotation, linker);
}
if (type != null) {
return new TypeRef(typeToString(type), new Array<TypeLink>(0));
}
return null;
}
- 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 |
|
|