zenadoc 0.0.2-preview.1

Extracts a Zena package's public API as JSON

Readme Files Dependencies Versions

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 from zena-package.json or the filesystem (loadPackage, Package, ModuleSpec)
  • zenadoc/model — API documentation model (DocPackage, DocModule, DocDeclaration, DocMember, TypeRef, TypeLink, DeclarationKind, MemberKind)
  • zenadoc/json — serializes a DocPackage to JSON (packageToJson)
  • zenadoc/extract — walks a parsed Module AST into a DocModule (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
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19
  • compiler compiler.zena-lang.pkg.zena-lang.dev 0.0.2-preview.1