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

2.0 KiB Raw
/**
 * Resolving a type reference to the declaration it names.
 *
 * Scope analysis already records a symbol for every type-reference
 * node — it is what the checker resolves a `NamedTypeAnnotation`
 * through — so a link is a lookup rather than a second name
 * resolution. Going through the symbol is what makes the link exact:
 * a type parameter `T` and a class named `T` render identically and
 * resolve differently, and an imported name resolves to the module
 * that declares it rather than the one that imports it.
 */

import { Node, TypeParameter } from 'compiler/ast';
import { SemanticModel } from 'compiler/semantic-model';
import { Naming } from './ids.zena';
import { TypeLinker } from './type-text.zena';

/** Links type references using one module's semantic model. */
export final class ModelLinker implements TypeLinker {
  // Nullable rather than the caller holding a `ModelLinker | null`,
  // which cannot be passed where `TypeLinker | null` is expected:
  // https://code.rictic.com/justin/zena/issues/476.
  #model: SemanticModel | null;
  #naming: Naming;

  new(model: SemanticModel | null, naming: Naming)
    : #model = model, #naming = naming;

  idFor(annotation: Node): String | null {
    let model = this.#model;
    if (model == null) {
      return null;
    }
    // `symbol` is a keyword, hence `found`.
    let found = model.resolve(annotation);
    if (found == null) {
      return null;
    }
    // Follow imports to whatever finally declares the name.
    let target = found.resolveTarget();
    let declaration = target.declaration;
    if (declaration == null) {
      // A builtin: `i32`, `String` before the prelude declares it. There
      // is no page to point at.
      return null;
    }
    // A type parameter is scoped to the declaration that introduces it,
    // so it names nothing a reader can navigate to.
    if (declaration is TypeParameter) {
      return null;
    }
    if (target.name.length == 0) {
      return null;
    }
    return `${this.#naming.idOf(target.modulePath)}#${target.name}`;
  }
}
  • 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