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.6 KiB
Raw
/**
* Serializing the API model.
*
* Field order is the order written here and `JsonObject` preserves it,
* so the same source produces the same bytes: the output can be checked
* in, diffed in review, and used as a snapshot test.
*
* Empty collections and null fields are omitted. A consumer reads a
* missing `members` the same way it reads an empty one, and leaving
* them out keeps a package's JSON readable by a person.
*/
import { JsonObject, JsonArray, JsonValue, stringify } from 'zena:json';
import { DocComment, DocTag } from 'compiler/doc-comment';
import {
DocDeclaration, DocLoc, DocMember, DocModule, DocPackage, DocParam,
DocReexport, DocTypeParam, TypeRef, DeclarationKind, declarationKindName,
memberKindName,
} from './model.zena';
/** The format version, so a consumer can refuse what it cannot read. */
export let ZENADOC_FORMAT_VERSION = 1;
/** The whole package as pretty-printed JSON. */
export function packageToJson(pkg: DocPackage): String {
return stringify(packageObject(pkg), ' ');
}
export function packageObject(pkg: DocPackage): JsonObject {
let out = new JsonObject();
out['zenadoc'] = new Box<f64>(ZENADOC_FORMAT_VERSION as f64);
let meta = new JsonObject();
meta['name'] = pkg.name;
meta['root'] = pkg.root;
let version = pkg.version;
if (version != null) {
meta['version'] = version;
}
out['package'] = meta;
let modules = new JsonArray();
for (let module in pkg.modules) {
modules.push(moduleObject(module));
}
out['modules'] = modules;
return out;
}
function moduleObject(module: DocModule): JsonObject {
let out = new JsonObject();
out['id'] = module.id;
out['name'] = module.name;
out['file'] = module.file;
putDoc(out, module.doc);
if (module.reexports.length > 0) {
let reexports = new JsonArray();
for (let reexport in module.reexports) {
reexports.push(reexportObject(reexport));
}
out['reexports'] = reexports;
}
let declarations = new JsonArray();
for (let declaration in module.declarations) {
declarations.push(declarationObject(declaration));
}
out['declarations'] = declarations;
return out;
}
function reexportObject(reexport: DocReexport): JsonObject {
let out = new JsonObject();
out['from'] = reexport.from;
let resolved = reexport.resolved;
if (resolved != null) {
out['resolved'] = resolved;
}
if (reexport.isAll) {
out['all'] = new Box<boolean>(true);
} else {
let names = new JsonArray();
for (let name in reexport.names) {
names.push(name.exported);
}
out['names'] = names;
}
return out;
}
function declarationObject(declaration: DocDeclaration): JsonObject {
let out = new JsonObject();
out['kind'] = declarationKindName(declaration.kind);
out['name'] = declaration.name;
out['id'] = declaration.id;
out['anchor'] = declaration.anchor;
out['signature'] = declaration.signature;
if (!declaration.exported) {
out['exported'] = new Box<boolean>(false);
}
let reexportedFrom = declaration.reexportedFrom;
if (reexportedFrom != null) {
out['reexportedFrom'] = reexportedFrom;
}
if (declaration.modifiers.length > 0) {
out['modifiers'] = stringArray(declaration.modifiers);
}
putTypeParams(out, declaration.typeParameters);
putParams(out, declaration.parameters);
putType(out, 'type', declaration.type);
putType(out, 'extends', declaration.superClass);
// An interface's supertypes are written `extends`, a class's
// `implements`; the model holds one list, and the key says which
// keyword the source used.
let supertypeKey = if (declaration.kind == DeclarationKind.Interface) {
'extends'
} else {
'implements'
};
putTypes(out, supertypeKey, declaration.interfaces);
putTypes(out, 'mixins', declaration.mixins);
putDoc(out, declaration.doc);
putLoc(out, declaration.loc);
if (declaration.members.length > 0) {
let members = new JsonArray();
for (let member in declaration.members) {
members.push(memberObject(member));
}
out['members'] = members;
}
return out;
}
function memberObject(member: DocMember): JsonObject {
let out = new JsonObject();
out['kind'] = memberKindName(member.kind);
out['name'] = member.name;
out['id'] = member.id;
out['anchor'] = member.anchor;
out['signature'] = member.signature;
if (member.isStatic) {
out['static'] = new Box<boolean>(true);
}
if (member.isAbstract) {
out['abstract'] = new Box<boolean>(true);
}
let inheritedFrom = member.inheritedFrom;
if (inheritedFrom != null) {
out['inheritedFrom'] = inheritedFrom;
}
let mutability = member.mutability;
if (mutability != null) {
out['mutability'] = mutability;
}
putTypeParams(out, member.typeParameters);
putParams(out, member.parameters);
putType(out, 'type', member.type);
putDoc(out, member.doc);
putLoc(out, member.loc);
return out;
}
function putTypeParams(out: JsonObject, params: Array<DocTypeParam>): void {
if (params.length == 0) {
return;
}
let array = new JsonArray();
for (let param in params) {
let entry = new JsonObject();
entry['name'] = param.name;
putType(entry, 'bound', param.bound);
putType(entry, 'default', param.defaultType);
array.push(entry);
}
out['typeParameters'] = array;
}
function putParams(out: JsonObject, params: Array<DocParam>): void {
if (params.length == 0) {
return;
}
let array = new JsonArray();
for (let param in params) {
let entry = new JsonObject();
entry['name'] = param.name;
putType(entry, 'type', param.type);
if (param.optional) {
entry['optional'] = new Box<boolean>(true);
}
let fallback = param.defaultValue;
if (fallback != null) {
entry['default'] = fallback;
}
array.push(entry);
}
out['parameters'] = array;
}
function typeObject(type: TypeRef) {
let entry = new JsonObject();
entry['text'] = type.text;
if (type.links.length > 0) {
let links = new JsonArray();
for (let link in type.links) {
let one = new JsonObject();
one['start'] = new Box<f64>(link.start as f64);
one['end'] = new Box<f64>(link.end as f64);
one['id'] = link.id;
links.push(one);
}
entry['links'] = links;
}
return entry;
}
function putType(out: JsonObject, key: String, type: TypeRef | null): void {
if (type == null) {
return;
}
out[key] = typeObject(type);
}
function putTypes(out: JsonObject, key: String, types: Array<TypeRef>): void {
if (types.length == 0) {
return;
}
let array = new JsonArray();
for (let type in types) {
array.push(typeObject(type));
}
out[key] = array;
}
function putDoc(out: JsonObject, doc: DocComment | null): void {
if (doc == null) {
return;
}
let entry = new JsonObject();
if (doc.summary.length > 0) {
entry['summary'] = doc.summary;
}
if (doc.description.length > 0) {
entry['description'] = doc.description;
}
if (doc.tags.length > 0) {
let tags = new JsonArray();
for (let tag in doc.tags) {
let tagObject = new JsonObject();
tagObject['tag'] = tag.name;
if (tag.subject.length > 0) {
tagObject['name'] = tag.subject;
}
if (tag.text.length > 0) {
tagObject['text'] = tag.text;
}
tags.push(tagObject);
}
entry['tags'] = tags;
}
out['doc'] = entry;
}
function putLoc(out: JsonObject, loc: DocLoc | null): void {
if (loc == null) {
return;
}
let entry = new JsonObject();
entry['file'] = loc.file;
entry['line'] = new Box<f64>(loc.line as f64);
entry['column'] = new Box<f64>(loc.column as f64);
out['loc'] = entry;
}
function stringArray(values: Array<String>): JsonArray {
let array = new JsonArray();
for (let value in values) {
array.push(value);
}
return array;
}
- 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 |
|
|