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

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
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19
  • compiler compiler.zena-lang.pkg.zena-lang.dev 0.0.2-preview.1