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
11.2 KiB
Raw
/**
* The API model: what zenadoc extracts and what its JSON serializes.
*
* One `DocPackage` per run, holding one `DocModule` per module the
* package exports, each holding the declarations that module exports.
* The shape is described in docs/design/zenadoc.md.
*/
import { DocComment } from 'compiler/doc-comment';
import { StringBuilder } from 'zena:core';
/** Where a declaration was written, relative to the package root. */
export final class DocLoc(file: String, line: i32, column: i32)
/**
* A span of a rendered type that names a declaration.
*
* `start` and `end` are byte offsets into the `TypeRef`'s text. Type
* text is ASCII apart from a string-literal type, so a consumer can
* slice with them directly.
*/
export final class TypeLink(start: i32, end: i32, var id: String)
/**
* A type, rendered as text, plus the spans within it that name a
* declaration.
*
* Text with offsets rather than a type tree: rendering Zena's type
* syntax happens once, here, instead of in every consumer, and the
* offsets keep the links exact where matching names would not be — a
* type parameter `T` and a class `T` render the same and link
* differently.
*/
export final class TypeRef(text: String, links: Array<TypeLink>)
/** A declaration's type parameter. */
export final class DocTypeParam(
name: String,
bound: TypeRef | null,
defaultType: TypeRef | null
)
/** A parameter of a function, method, or constructor. */
export final class DocParam(
name: String,
type: TypeRef | null,
optional: boolean,
/** The default's source text, or null when there is none. */
defaultValue: String | null
)
/** What a member is. */
export enum MemberKind {
Field,
Method,
Constructor,
Getter,
Setter,
Operator,
EnumMember,
Variant,
}
export function memberKindName(kind: MemberKind): String {
return match (kind) {
case MemberKind.Field: 'field'
case MemberKind.Method: 'method'
case MemberKind.Constructor: 'constructor'
case MemberKind.Getter: 'getter'
case MemberKind.Setter: 'setter'
case MemberKind.Operator: 'operator'
case MemberKind.EnumMember: 'enumMember'
case MemberKind.Variant: 'variant'
};
}
/** A member of a class, interface, mixin, or enum. */
export final class DocMember {
kind: MemberKind;
name: String;
/** `<module id>#<Owner>.<name>`. */
id: String;
/** A URL fragment for this member, unique within its module. */
anchor: String;
/** The member as it would be written, without a body. */
signature: String;
var isStatic: boolean = false;
var isAbstract: boolean = false;
/** `let`, `var`, or null for members that are not fields. */
var mutability: String | null = null;
var typeParameters = new Array<DocTypeParam>(0);
var parameters = new Array<DocParam>(0);
var type: TypeRef | null = null;
var doc: DocComment | null = null;
var loc: DocLoc | null = null;
/**
* The declaration this member is inherited from, when it is not
* declared on the one documenting it. Null for a member written here.
*/
var inheritedFrom: String | null = null;
new(this.kind, this.name, this.id, this.anchor, this.signature);
}
/** What a declaration is. */
export enum DeclarationKind {
Function,
Variable,
Class,
Interface,
Mixin,
Enum,
TypeAlias,
Symbol,
}
export function declarationKindName(kind: DeclarationKind): String {
return match (kind) {
case DeclarationKind.Function: 'function'
case DeclarationKind.Variable: 'variable'
case DeclarationKind.Class: 'class'
case DeclarationKind.Interface: 'interface'
case DeclarationKind.Mixin: 'mixin'
case DeclarationKind.Enum: 'enum'
case DeclarationKind.TypeAlias: 'typeAlias'
case DeclarationKind.Symbol: 'symbol'
};
}
/** A top-level declaration of a module. */
export final class DocDeclaration {
kind: DeclarationKind;
name: String;
/** `<module id>#<name>`. */
id: String;
/** A URL fragment for this declaration, unique within its module. */
anchor: String;
/** The declaration as it would be written, without a body. */
signature: String;
/** Whether the module exports it. */
var exported: boolean = true;
/** Declaration keywords: `final`, `sealed`, `abstract`, `resource`, … */
var modifiers = new Array<String>(0);
var typeParameters = new Array<DocTypeParam>(0);
/** Parameters, for functions and variables holding a function. */
var parameters = new Array<DocParam>(0);
/** A function's return type, a variable's type, an alias's target. */
var type: TypeRef | null = null;
var superClass: TypeRef | null = null;
var interfaces = new Array<TypeRef>(0);
var mixins = new Array<TypeRef>(0);
var members = new Array<DocMember>(0);
var doc: DocComment | null = null;
var loc: DocLoc | null = null;
/**
* The canonical id of the module that declares this, when the module
* documenting it only re-exports it. Null for a declaration written
* in the module it is documented in.
*/
var reexportedFrom: String | null = null;
/**
* The id this declaration had in the module that declares it, when
* this is a re-exported copy. A type reference resolves to that id,
* and the page a reader can open is this copy's, so serialization
* rewrites one to the other.
*/
var originalId: String | null = null;
new(this.kind, this.name, this.id, this.anchor, this.signature);
/** A copy carrying a new name, id, and anchor. */
renamed(name: String, id: String, anchor: String): DocDeclaration {
let out = new DocDeclaration(this.kind, name, id, anchor, this.signature);
out.exported = this.exported;
out.modifiers = this.modifiers;
out.typeParameters = this.typeParameters;
out.parameters = this.parameters;
out.type = this.type;
out.superClass = this.superClass;
out.interfaces = this.interfaces;
out.mixins = this.mixins;
out.members = this.members;
out.doc = this.doc;
out.loc = this.loc;
out.reexportedFrom = this.reexportedFrom;
out.originalId = this.id;
return out;
}
}
/** One name a re-export carries, and what it is called at the source. */
export final class DocReexportName(
/** The name this module exports it as. */
exported: String,
/** The name the source module exports it as. */
source: String
)
/**
* A re-export a module performs.
*
* The module walk sees one module at a time, so it records the
* specifier as written. Resolving it to the declarations it carries
* needs the whole package, and happens after every module is walked.
*/
export final class DocReexport(
/** The module specifier re-exported from, as written. */
from: String,
/** The names re-exported, empty for `export * from`. */
names: Array<DocReexportName>,
/** Whether this is `export * from`. */
isAll: boolean
) {
/** The canonical id `from` resolves to, once that is known. */
var resolved: String | null = null;
}
/** One module of a package. */
export final class DocModule {
/** The import specifier, e.g. `zena:array`. */
id: String;
/** The module's name within its package, e.g. `array`. */
name: String;
/** The entry file, relative to the package root. */
file: String;
/**
* The id the compiler loads this module by, when it differs from
* `id`. A manifest module whose entry file is not `<name>.zena`
* canonicalizes to a path id — `zena:byte-buffer` loads
* `zena:core/byte-buffer.zena` — and a type reference into it
* resolves to that path, not to the name a reader sees.
*/
var canonicalId: String | null = null;
var doc: DocComment | null = null;
var declarations = new Array<DocDeclaration>(0);
var reexports = new Array<DocReexport>(0);
/**
* Anchors handed out in this module. Kept on the module because
* resolving re-exports adds declarations after the walk, and their
* anchors have to stay unique against the ones already given out.
*/
anchors = new AnchorSet();
new(this.id, this.name, this.file);
/** Whether a declaration of this name is already documented here. */
declares(name: String): boolean {
for (let declaration in this.declarations) {
if (declaration.name == name) {
return true;
}
}
return false;
}
}
/** Everything one run extracts. */
export final class DocPackage {
name: String;
/** The package root, relative to where zenadoc ran. */
root: String;
var version: String | null = null;
var modules = new Array<DocModule>(0);
new(this.name, this.root);
}
/**
* A member name with its punctuation spelled out.
*
* Operator names are punctuation, and a slug built from them alone is
* empty: `operator +` and `operator -` would both anchor at
* `operator`, and the second would silently become `operator-2`.
*/
export function readableName(name: String): String {
if (name == '<constructor>') {
return 'constructor';
}
let word = operatorWord(name);
if (word != null) {
return 'operator ' + word;
}
return name;
}
function operatorWord(name: String): String | null {
if (name == '+') { return 'plus'; }
if (name == '-') { return 'minus'; }
if (name == '*') { return 'times'; }
if (name == '**') { return 'power'; }
if (name == '/') { return 'divide'; }
if (name == '%') { return 'modulo'; }
if (name == '==') { return 'equals'; }
if (name == '<') { return 'less-than'; }
if (name == '>') { return 'greater-than'; }
if (name == '<=') { return 'less-or-equal'; }
if (name == '>=') { return 'greater-or-equal'; }
if (name == '[]') { return 'index'; }
if (name == '[]=') { return 'index-set'; }
if (name == '&') { return 'and'; }
if (name == '|') { return 'or'; }
if (name == '^') { return 'xor'; }
if (name == '~') { return 'not'; }
if (name == '<<') { return 'shift-left'; }
if (name == '>>') { return 'shift-right'; }
if (name == '>>>') { return 'unsigned-shift-right'; }
return null;
}
/**
* A URL fragment for a declaration or member name.
*
* Lowercased, with every byte that is not an ASCII letter or digit
* replaced by `-` and runs collapsed. Uniqueness within a module is the
* caller's job — see `AnchorSet`.
*/
export function anchorFor(name: String): String {
let sb = new StringBuilder(name.length);
var lastWasDash = false;
var wrote = false;
var i = 0;
while (i < name.length) {
let b = name.getByteAt(i);
let isDigit = b >= 48 && b <= 57;
let isLower = b >= 97 && b <= 122;
let isUpper = b >= 65 && b <= 90;
if (isDigit || isLower) {
sb.appendByte(b);
lastWasDash = false;
wrote = true;
} else if (isUpper) {
sb.appendByte(b + 32);
lastWasDash = false;
wrote = true;
} else if (wrote && !lastWasDash) {
sb.appendByte(45);
lastWasDash = true;
}
i += 1;
}
let s = sb.toString();
// A trailing dash reads as a typo in a URL, and `operator []` would
// end in one.
if (s.length > 0 && s.getByteAt(s.length - 1) == 45) {
return s.sliceBytes(0, s.length - 1);
}
if (s.length == 0) {
return 'x';
}
return s;
}
/** Hands out anchors that are unique within one module. */
export final class AnchorSet {
#used = new Map<String, i32>();
/** The anchor for a name, suffixed if the base is already taken. */
take(name: String): String {
let base = anchorFor(readableName(name));
if (!this.#used.has(base)) {
this.#used[base] = 1;
return base;
}
let n = this.#used[base] + 1;
this.#used[base] = n;
return `${base}-${i32ToString(n)}`;
}
}
- 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 |
|
|