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

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