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

29.4 KiB Raw
/**
 * Walking one module's AST into the API model.
 *
 * The walk is syntactic: a declaration documents the modifiers,
 * parameters and annotations its author wrote. The checker's types are
 * consulted only where the source has no annotation to render, which is
 * why extraction works on a module that does not type-check.
 *
 * Only exported declarations and public members are documented unless
 * `ExtractOptions.includePrivate` says otherwise. See
 * docs/design/zenadoc.md.
 */

import {
  Module, Node, Statement, TypeAnnotation, RecordTypeAnnotation,
  PropertySignature, Parameter, TypeParameter,
  Identifier, IdentifierPattern, SymbolPropertyName,
  ClassDeclaration, InterfaceDeclaration, MixinDeclaration, EnumDeclaration,
  TypeAliasDeclaration, VariableDeclaration, FunctionDeclaration,
  DeclareFunction, SymbolDeclaration, ExportAllDeclaration,
  ExportFromDeclaration, FieldDefinition, MethodDefinition,
  AccessorDeclaration, MethodSignature, AccessorSignature, EnumMember,
  CaseClassParam, SealedVariant, FunctionExpression, SourceLocation,
} from 'compiler/ast';
import { lineAt, columnAt } from 'compiler/line-index';
import { CommentMap, attachComments } from 'compiler/comment-attachment';
import { SemanticModel } from 'compiler/semantic-model';
import { Type } from 'compiler/types';
import { DocComment, parseLeadingDoc } from 'compiler/doc-comment';
import {
  AnchorSet, DocDeclaration, DocLoc, DocMember, DocModule, DocParam,
  DocReexport, DocReexportName, DocTypeParam, DeclarationKind, MemberKind,
  TypeRef, readableName,
} from './model.zena';
import {
  annotationRef, annotationText, refFor, refForOrType, TypeLinker,
} from './type-text.zena';
import { StringBuilder, growable } from 'zena:core';

/** What to document. */
export final class ExtractOptions {
  /** Document non-exported declarations and `#private` members. */
  var includePrivate: boolean = false;


}

/** State threaded through one module's walk. */
final class Walk {
  moduleId: String;
  file: String;
  source: String;
  comments: CommentMap;
  model: SemanticModel | null;
  options: ExtractOptions;
  anchors: AnchorSet;
  linker: TypeLinker | null;

  new(this.moduleId, this.file, this.source, this.comments, this.model,
      this.options, this.anchors, this.linker);

  /** A type reference for an optional annotation. */
  ref(annotation: TypeAnnotation | null): TypeRef | null {
    return refFor(annotation, this.linker);
  }

  /** A type reference for an annotation that is always present. */
  refOf(annotation: TypeAnnotation): TypeRef {
    return annotationRef(annotation, this.linker);
  }

  /** Type references for a list of annotations. */
  refsOf(
    annotations: GrowableArray<TypeAnnotation> | null
  ): GrowableArray<TypeRef> {
    let out = new Array<TypeRef>(0);
    if (annotations == null) {
      return out;
    }
    for (let annotation in annotations) {
      out.push(this.refOf(annotation));
    }
    return out;
  }

  /** Whether a name is public — that is, not `#private`. */
  visible(name: String): boolean {
    if (this.options.includePrivate) {
      return true;
    }
    return name.length == 0 || name.getByteAt(0) != 35;
  }

  docFor(node: Node): DocComment | null {
    let leading = this.comments.getLeading(node);
    if (leading == null) {
      return null;
    }
    return parseLeadingDoc(leading);
  }

  locFor(loc: SourceLocation | null): DocLoc | null {
    if (loc == null) {
      return null;
    }
    return new DocLoc(this.file, lineAt(loc.path, loc.start),
        columnAt(loc.path, loc.start));
  }

  /** The source text a node covers, for rendering default values. */
  textOf(loc: SourceLocation | null): String | null {
    if (loc == null) {
      return null;
    }
    if (loc.start < 0 || loc.end > this.source.length || loc.end < loc.start) {
      return null;
    }
    return this.source.sliceBytes(loc.start, loc.end);
  }
}

/**
 * Extracts one module.
 *
 * `model` may be null: without it, declarations that rely on inference
 * document with no type rather than with a wrong one.
 */
export function extractModule(
  moduleId: String,
  name: String,
  file: String,
  ast: Module,
  model: SemanticModel | null,
  options: ExtractOptions,
  linker: TypeLinker | null = null
): DocModule {
  let out = new DocModule(moduleId, name, file);
  let walk = new Walk(moduleId, file, ast.source, attachComments(ast), model,
      options, out.anchors, linker);
  out.doc = walk.docFor(ast);

  let declarations = new Array<DocDeclaration>(8);
  let reexports = new Array<DocReexport>(0);
  for (let statement in ast.body) {
    match (statement) {
      case ExportAllDeclaration as exportAll: {
        reexports.push(new DocReexport(exportAll.moduleSpecifier.value,
            new Array<DocReexportName>(0), true));
      }
      case ExportFromDeclaration as exportFrom: {
        let names = new Array<DocReexportName>(
            exportFrom.specifiers.length);
        for (let spec in exportFrom.specifiers) {
          names.push(new DocReexportName(spec.local.name, spec.imported.name));
        }
        reexports.push(new DocReexport(exportFrom.moduleSpecifier.value, names,
            false));
      }
      case _: {
        let declaration = declarationOf(walk, statement);
        if (declaration != null) {
          declarations.push(declaration);
        }
      }
    }
  }
  out.declarations = declarations;
  out.reexports = reexports;
  return out;
}

/** The declaration a statement makes, or null if it makes none. */
function declarationOf(walk: Walk, statement: Statement): DocDeclaration | null {
  return match (statement) {
  case ClassDeclaration as decl: classDeclaration(walk, decl)
  case InterfaceDeclaration as decl: interfaceDeclaration(walk, decl)
  case MixinDeclaration as decl: mixinDeclaration(walk, decl)
  case EnumDeclaration as decl: enumDeclaration(walk, decl)
  case TypeAliasDeclaration as decl: typeAliasDeclaration(walk, decl)
  case VariableDeclaration as decl: variableDeclaration(walk, decl)
  case FunctionDeclaration as decl: functionDeclaration(walk, decl)
  case DeclareFunction as decl: declareFunction(walk, decl)
  case SymbolDeclaration as decl: symbolDeclaration(walk, decl)
  case _: null
};
}

/** Whether a declaration is documented at all. */
function included(walk: Walk, exported: boolean, name: String) {
  return (exported || walk.options.includePrivate) && walk.visible(name);
}

function start(
  walk: Walk,
  kind: DeclarationKind,
  name: String,
  signature: String
) {
  let id = `${walk.moduleId}#${name}`;
  return new DocDeclaration(kind, name, id, walk.anchors.take(name), signature);
}

// ============================================================================
// Declarations
// ============================================================================

function classDeclaration(
  walk: Walk,
  decl: ClassDeclaration
): DocDeclaration | null {
  if (!included(walk, decl.exported, decl.name.name)) {
    return null;
  }
  let modifiers = new Array<String>(2);
  if (decl.isFinal) { modifiers.push('final'); }
  if (decl.isAbstract) { modifiers.push('abstract'); }
  if (decl.isSealed) { modifiers.push('sealed'); }
  if (decl.isResource) { modifiers.push('resource'); }
  if (decl.isExtension) { modifiers.push('extension'); }

  let typeParams = typeParameters(walk, decl.typeParameters);
  let sb = new StringBuilder(64);
  for (let modifier in modifiers) {
    sb.append(modifier);
    sb.append(' ');
  }
  sb.append('class ');
  sb.append(decl.name.name);
  sb.append(typeParameterText(typeParams));
  let caseParams = decl.caseParams;
  if (caseParams != null) {
    sb.append('(');
    sb.append(caseParamText(walk, caseParams));
    sb.append(')');
  }
  let superClass = decl.superClass;
  if (superClass != null) {
    sb.append(' extends ');
    sb.append(annotationText(superClass));
  }
  let mixins = decl.mixins;
  if (mixins != null && mixins.length > 0) {
    sb.append(' with ');
    sb.append(annotationList(mixins));
  }
  let interfaces = decl.implementsList;
  if (interfaces != null && interfaces.length > 0) {
    sb.append(' implements ');
    sb.append(annotationList(interfaces));
  }

  let out = start(walk, DeclarationKind.Class, decl.name.name, sb.toString());
  out.exported = decl.exported;
  out.modifiers = modifiers;
  out.typeParameters = typeParams;
  out.doc = walk.docFor(decl);
  out.loc = walk.locFor(decl.loc);
  out.superClass = walk.ref(decl.superClass);
  out.interfaces = walk.refsOf(decl.implementsList);
  out.mixins = walk.refsOf(decl.mixins);

  let members = new Array<DocMember>(8);
  if (caseParams != null) {
    // A case class's parameters are its fields, and nothing else in the
    // body declares them.
    for (let param in caseParams) {
      let member = caseParamMember(walk, out, param);
      if (member != null) {
        members.push(member);
      }
    }
  }
  let variants = decl.sealedVariants;
  if (variants != null) {
    for (let variant in variants) {
      members.push(variantMember(walk, out, variant));
    }
  }
  collectMembers(walk, out, decl.body, members);
  out.members = members;
  return out;
}

function interfaceDeclaration(
  walk: Walk,
  decl: InterfaceDeclaration
): DocDeclaration | null {
  if (!included(walk, decl.exported, decl.name.name)) {
    return null;
  }
  let typeParams = typeParameters(walk, decl.typeParameters);
  let sb = new StringBuilder(64);
  sb.append('interface ');
  sb.append(decl.name.name);
  sb.append(typeParameterText(typeParams));
  let extendsList = decl.extendsList;
  if (extendsList != null && extendsList.length > 0) {
    sb.append(' extends ');
    sb.append(annotationList(extendsList));
  }

  let out = start(walk, DeclarationKind.Interface, decl.name.name,
      sb.toString());
  out.exported = decl.exported;
  out.typeParameters = typeParams;
  out.doc = walk.docFor(decl);
  out.loc = walk.locFor(decl.loc);
  out.interfaces = walk.refsOf(decl.extendsList);
  let members = new Array<DocMember>(8);
  collectMembers(walk, out, decl.body, members);
  out.members = members;
  return out;
}

function mixinDeclaration(
  walk: Walk,
  decl: MixinDeclaration
): DocDeclaration | null {
  if (!included(walk, decl.exported, decl.name.name)) {
    return null;
  }
  let typeParams = typeParameters(walk, decl.typeParameters);
  let sb = new StringBuilder(64);
  sb.append('mixin ');
  sb.append(decl.name.name);
  sb.append(typeParameterText(typeParams));
  let on = decl.on;
  if (on != null) {
    sb.append(' on ');
    sb.append(annotationText(on));
  }
  let mixins = decl.mixins;
  if (mixins != null && mixins.length > 0) {
    sb.append(' with ');
    sb.append(annotationList(mixins));
  }

  let out = start(walk, DeclarationKind.Mixin, decl.name.name, sb.toString());
  out.exported = decl.exported;
  out.typeParameters = typeParams;
  out.doc = walk.docFor(decl);
  out.loc = walk.locFor(decl.loc);
  out.superClass = walk.ref(decl.on);
  out.mixins = walk.refsOf(decl.mixins);
  let members = new Array<DocMember>(8);
  collectMembers(walk, out, decl.body, members);
  out.members = members;
  return out;
}

function enumDeclaration(
  walk: Walk,
  decl: EnumDeclaration
): DocDeclaration | null {
  if (!included(walk, decl.exported, decl.name.name)) {
    return null;
  }
  let out = start(walk, DeclarationKind.Enum, decl.name.name,
      'enum ' + decl.name.name);
  out.exported = decl.exported;
  out.doc = walk.docFor(decl);
  out.loc = walk.locFor(decl.loc);
  let members = new Array<DocMember>(decl.members.length);
  for (let member in decl.members) {
    let name = member.name.name;
    let entry = new DocMember(MemberKind.EnumMember, name,
        `${out.id}.${name}`,
        walk.anchors.take(`${decl.name.name} ${readableName(name)}`), name);
    entry.doc = walk.docFor(member);
    entry.loc = walk.locFor(member.loc);
    members.push(entry);
  }
  out.members = members;
  return out;
}

function typeAliasDeclaration(
  walk: Walk,
  decl: TypeAliasDeclaration
): DocDeclaration | null {
  if (!included(walk, decl.exported, decl.name.name)) {
    return null;
  }
  let typeParams = typeParameters(walk, decl.typeParameters);
  let modifiers = new Array<String>(2);
  if (decl.isOpaque) {
    modifiers.push('opaque');
  } else if (decl.isDistinct) {
    modifiers.push('distinct');
  }
  let sb = new StringBuilder(64);
  sb.append('type ');
  sb.append(decl.name.name);
  sb.append(typeParameterText(typeParams));
  let target = decl.typeAnnotation;
  if (target != null) {
    sb.append(' = ');
    sb.append(annotationText(target));
  }

  let out = start(walk, DeclarationKind.TypeAlias, decl.name.name,
      sb.toString());
  out.exported = decl.exported;
  out.modifiers = modifiers;
  out.typeParameters = typeParams;
  out.type = walk.ref(decl.typeAnnotation);
  out.doc = walk.docFor(decl);
  out.loc = walk.locFor(decl.loc);
  if (target != null) {
    if (let RecordTypeAnnotation {properties} = target) {
      let members = new Array<DocMember>(properties.length);
      for (let prop in properties) {
        let member = recordPropertyMember(walk, out, prop);
        if (member != null) {
          members.push(member);
        }
      }
      out.members = members;
    }
  }
  return out;
}

/** A property of a record type alias. */
function recordPropertyMember(
  walk: Walk,
  owner: DocDeclaration,
  prop: PropertySignature
): DocMember | null {
  let name = prop.name.name;
  if (!walk.visible(name)) {
    return null;
  }
  let type = walk.refOf(prop.typeAnnotation);
  let sb = new StringBuilder(48);
  sb.append(name);
  if (prop.optional) {
    sb.append('?');
  }
  sb.append(': ');
  sb.append(type.text);

  let out = startMember(walk, owner, MemberKind.Field, name, sb.toString());
  out.type = type;
  out.doc = walk.docFor(prop);
  out.loc = walk.locFor(prop.loc);
  return out;
}

/**
 * A module-level `let` or `var`.
 *
 * An arrow function bound to a name is the way Zena writes most
 * functions, so a variable whose initializer is one documents as a
 * function.
 */
function variableDeclaration(
  walk: Walk,
  decl: VariableDeclaration
): DocDeclaration | null {
  let name = patternName(decl.pattern);
  if (name == null) {
    return null;
  }
  if (!included(walk, decl.exported, name)) {
    return null;
  }
  let fn = arrowOf(decl);
  if (fn != null) {
    return functionLike(walk, decl, name, fn, decl.exported, decl.loc);
  }
  let type = refForOrType(decl.typeAnnotation, nodeType(walk, decl.pattern), walk.linker);
  let sb = new StringBuilder(48);
  sb.append(decl.kind);
  sb.append(' ');
  sb.append(name);
  if (type != null) {
    sb.append(': ');
    sb.append(type.text);
  }

  let out = start(walk, DeclarationKind.Variable, name, sb.toString());
  out.exported = decl.exported;
  let modifiers = growable<String>([decl.kind]);
  out.modifiers = modifiers;
  out.type = type;
  out.doc = walk.docFor(decl);
  out.loc = walk.locFor(decl.loc);
  return out;
}

function functionDeclaration(
  walk: Walk,
  decl: FunctionDeclaration
): DocDeclaration | null {
  let name = patternName(decl.name);
  if (name == null || !included(walk, decl.exported, name)) {
    return null;
  }
  return functionLike(walk, decl, name, decl.func, decl.exported, decl.loc);
}

function declareFunction(
  walk: Walk,
  decl: DeclareFunction
): DocDeclaration | null {
  if (!included(walk, decl.exported, decl.name.name)) {
    return null;
  }
  let typeParams = typeParameters(walk, decl.typeParameters);
  let params = parameters(walk, decl.params);
  let returns = walk.ref(decl.returnType);
  let out = start(walk, DeclarationKind.Function, decl.name.name,
      'declare function ' + decl.name.name + typeParameterText(typeParams) +
          parameterText(params) + returnText(returns));
  out.exported = decl.exported;
  let modifiers = growable<String>(['declare']);
  out.modifiers = modifiers;
  out.typeParameters = typeParams;
  out.parameters = params;
  out.type = returns;
  out.doc = walk.docFor(decl);
  out.loc = walk.locFor(decl.loc);
  return out;
}

function symbolDeclaration(
  walk: Walk,
  decl: SymbolDeclaration
): DocDeclaration | null {
  if (!included(walk, decl.exported, decl.name.name)) {
    return null;
  }
  let out = start(walk, DeclarationKind.Symbol, decl.name.name,
      'symbol ' + decl.name.name);
  out.exported = decl.exported;
  out.doc = walk.docFor(decl);
  out.loc = walk.locFor(decl.loc);
  return out;
}

/** A named function, however it was written. */
function functionLike(
  walk: Walk,
  docNode: Node,
  name: String,
  fn: FunctionExpression,
  exported: boolean,
  loc: SourceLocation | null
): DocDeclaration {
  let typeParams = typeParameters(walk, fn.typeParameters);
  let params = parameters(walk, fn.params);
  let returns = walk.ref(fn.returnType);
  let modifiers = new Array<String>(2);
  if (fn.isAsync) { modifiers.push('async'); }
  if (fn.isGenerator) { modifiers.push('generator'); }

  let sb = new StringBuilder(64);
  if (fn.isAsync) {
    sb.append('async ');
  }
  sb.append('function ');
  sb.append(name);
  sb.append(typeParameterText(typeParams));
  sb.append(parameterText(params));
  sb.append(returnText(returns));

  let out = start(walk, DeclarationKind.Function, name, sb.toString());
  out.exported = exported;
  out.modifiers = modifiers;
  out.typeParameters = typeParams;
  out.parameters = params;
  out.type = returns;
  out.doc = walk.docFor(docNode);
  out.loc = walk.locFor(loc);
  return out;
}

// ============================================================================
// Members
// ============================================================================

function collectMembers(
  walk: Walk,
  owner: DocDeclaration,
  body: Array<Node>,
  out: GrowableArray<DocMember>
): void {
  for (let node in body) {
    let member = memberOf(walk, owner, node);
    if (member != null) {
      out.push(member);
    }
  }
}

function memberOf(
  walk: Walk,
  owner: DocDeclaration,
  node: Node
): DocMember | null {
  return match (node) {
  case FieldDefinition as field: fieldMember(walk, owner, field)
  case MethodDefinition as method: methodMember(walk, owner, method)
  case AccessorDeclaration as accessor: accessorMember(walk, owner, accessor)
  case MethodSignature as signature: methodSignatureMember(walk, owner, signature)
  case AccessorSignature as signature: accessorSignatureMember(walk, owner, signature)
  case _: null
};
}

function startMember(
  walk: Walk,
  owner: DocDeclaration,
  kind: MemberKind,
  name: String,
  signature: String
) {
  return new DocMember(kind, name, `${owner.id}.${name}`,
    walk.anchors.take(`${owner.name} ${readableName(name)}`), signature);
}

function fieldMember(
  walk: Walk,
  owner: DocDeclaration,
  field: FieldDefinition
): DocMember | null {
  let name = memberName(field.name);
  if (name == null || !walk.visible(name)) {
    return null;
  }
  let type = walk.ref(field.typeAnnotation);
  let sb = new StringBuilder(48);
  if (field.isStatic) { sb.append('static '); }
  if (field.isAbstract) { sb.append('abstract '); }
  let mutability = field.mutability;
  if (mutability != null) {
    sb.append(mutability);
    sb.append(' ');
  }
  sb.append(name);
  if (type != null) {
    sb.append(': ');
    sb.append(type.text);
  }

  let out = startMember(walk, owner, MemberKind.Field, name, sb.toString());
  out.isStatic = field.isStatic;
  out.isAbstract = field.isAbstract;
  out.mutability = field.mutability;
  out.type = type;
  out.doc = walk.docFor(field);
  out.loc = walk.locFor(field.loc);
  return out;
}

function methodMember(
  walk: Walk,
  owner: DocDeclaration,
  method: MethodDefinition
): DocMember | null {
  let name = memberName(method.name);
  if (name == null || !walk.visible(name)) {
    return null;
  }
  // `new(...)` is the default constructor; `new name(...)` a named one
  // (on a class or an interface), shown under its name.
  let isDefaultConstructor = name == '<constructor>';
  let isConstructor = isDefaultConstructor || method.isConstructor;
  let kind = if (isConstructor) {
    MemberKind.Constructor
  } else if (isOperatorName(name)) {
    MemberKind.Operator
  } else {
    MemberKind.Method
  };
  let typeParams = typeParameters(walk, method.typeParameters);
  let params = parameters(walk, method.params);
  let returns = walk.ref(method.returnType);

  let sb = new StringBuilder(64);
  if (method.isStatic) { sb.append('static '); }
  if (method.isAbstract) { sb.append('abstract '); }
  if (method.isAsync) { sb.append('async '); }
  if (kind == MemberKind.Operator) {
    sb.append('operator ');
  }
  sb.append(if (isDefaultConstructor) { 'new' } else if (isConstructor) { 'new ' + name } else { name });
  sb.append(typeParameterText(typeParams));
  sb.append(parameterText(params));
  sb.append(returnText(returns));

  let out = startMember(walk, owner, kind,
      if (isDefaultConstructor) { 'new' } else { name }, sb.toString());
  out.isStatic = method.isStatic;
  out.isAbstract = method.isAbstract;
  out.typeParameters = typeParams;
  out.parameters = params;
  out.type = returns;
  out.doc = walk.docFor(method);
  out.loc = walk.locFor(method.loc);
  return out;
}

function accessorMember(
  walk: Walk,
  owner: DocDeclaration,
  accessor: AccessorDeclaration
): DocMember | null {
  let name = memberName(accessor.name);
  if (name == null || !walk.visible(name)) {
    return null;
  }
  let type = walk.refOf(accessor.typeAnnotation);
  let kind = if (accessor.getter != null) {
    MemberKind.Getter
  } else {
    MemberKind.Setter
  };
  let sb = new StringBuilder(48);
  if (accessor.isStatic) { sb.append('static '); }
  sb.append(name);
  sb.append(': ');
  sb.append(type.text);
  if (accessor.setter != null) {
    sb.append(if (accessor.getter != null) { ' { get; set; }' } else { ' { set; }' });
  } else {
    sb.append(' { get; }');
  }

  let out = startMember(walk, owner, kind, name, sb.toString());
  out.isStatic = accessor.isStatic;
  out.type = type;
  out.doc = walk.docFor(accessor);
  out.loc = walk.locFor(accessor.loc);
  return out;
}

function methodSignatureMember(
  walk: Walk,
  owner: DocDeclaration,
  signature: MethodSignature
): DocMember | null {
  let name = memberName(signature.name);
  if (name == null || !walk.visible(name)) {
    return null;
  }
  let typeParams = typeParameters(walk, signature.typeParameters);
  let params = parameters(walk, signature.params);
  let returns = walk.ref(signature.returnType);
  let kind = if (isOperatorName(name)) {
    MemberKind.Operator
  } else {
    MemberKind.Method
  };
  let sb = new StringBuilder(64);
  if (kind == MemberKind.Operator) {
    sb.append('operator ');
  }
  sb.append(name);
  sb.append(typeParameterText(typeParams));
  sb.append(parameterText(params));
  sb.append(returnText(returns));

  let out = startMember(walk, owner, kind, name, sb.toString());
  out.isAbstract = true;
  out.typeParameters = typeParams;
  out.parameters = params;
  out.type = returns;
  out.doc = walk.docFor(signature);
  out.loc = walk.locFor(signature.loc);
  return out;
}

function accessorSignatureMember(
  walk: Walk,
  owner: DocDeclaration,
  signature: AccessorSignature
): DocMember | null {
  let name = signature.name.name;
  if (!walk.visible(name)) {
    return null;
  }
  let type = walk.refOf(signature.typeAnnotation);
  let kind = if (signature.hasGetter) {
    MemberKind.Getter
  } else {
    MemberKind.Setter
  };
  let sb = new StringBuilder(48);
  sb.append(name);
  sb.append(': ');
  sb.append(type.text);
  if (signature.hasGetter && signature.hasSetter) {
    sb.append(' { get; set; }');
  } else if (signature.hasSetter) {
    sb.append(' { set; }');
  } else {
    sb.append(' { get; }');
  }

  let out = startMember(walk, owner, kind, name, sb.toString());
  out.isAbstract = true;
  out.type = type;
  out.doc = walk.docFor(signature);
  out.loc = walk.locFor(signature.loc);
  return out;
}

/** A case class's parameter, which is also a field. */
function caseParamMember(
  walk: Walk,
  owner: DocDeclaration,
  param: CaseClassParam
): DocMember | null {
  let name = param.name.name;
  if (!walk.visible(name)) {
    return null;
  }
  let type = walk.refOf(param.typeAnnotation);
  let sb = new StringBuilder(48);
  let mutability = param.mutability;
  if (mutability != null) {
    sb.append(mutability);
    sb.append(' ');
  }
  sb.append(name);
  sb.append(': ');
  sb.append(type.text);
  let defaultValue = param.defaultValue;
  if (defaultValue != null) {
    let fallback = walk.textOf(defaultValue.loc);
    if (fallback != null) {
      sb.append(' = ');
      sb.append(fallback);
    }
  }

  let out = startMember(walk, owner, MemberKind.Field, name, sb.toString());
  out.mutability = param.mutability;
  out.type = type;
  out.doc = walk.docFor(param);
  out.loc = walk.locFor(param.loc);
  return out;
}

/** One `case` of a sealed class. */
function variantMember(
  walk: Walk,
  owner: DocDeclaration,
  variant: SealedVariant
): DocMember {
  let name = variant.name.name;
  let sb = new StringBuilder(48);
  sb.append('case ');
  sb.append(name);
  let params = variant.params;
  if (params != null) {
    sb.append('(');
    sb.append(caseParamText(walk, params));
    sb.append(')');
  }
  let out = startMember(walk, owner, MemberKind.Variant, name, sb.toString());
  out.doc = walk.docFor(variant);
  out.loc = walk.locFor(variant.loc);
  return out;
}

// ============================================================================
// Shared pieces
// ============================================================================

function typeParameters(
  walk: Walk,
  params: GrowableArray<TypeParameter> | null
): GrowableArray<DocTypeParam> {
  let out = new Array<DocTypeParam>(0);
  if (params == null) {
    return out;
  }
  for (let param in params) {
    out.push(new DocTypeParam(param.name, walk.ref(param.constraint),
        walk.ref(param.defaultType)));
  }
  return out;
}

function typeParameterText(params: GrowableArray<DocTypeParam>): String {
  if (params.length == 0) {
    return '';
  }
  let sb = new StringBuilder(32);
  sb.append('<');
  var i = 0;
  while (i < params.length) {
    if (i > 0) {
      sb.append(', ');
    }
    let param = params[i];
    sb.append(param.name);
    let bound = param.bound;
    if (bound != null) {
      sb.append(' extends ');
      sb.append(bound.text);
    }
    let fallback = param.defaultType;
    if (fallback != null) {
      sb.append(' = ');
      sb.append(fallback.text);
    }
    i += 1;
  }
  sb.append('>');
  return sb.toString();
}

function parameters(
  walk: Walk,
  params: Array<Parameter>
): GrowableArray<DocParam> {
  let out = new Array<DocParam>(params.length);
  for (let param in params) {
    if (param.isThisParam) {
      continue;
    }
    let defaultValue = param.defaultValue;
    let fallback = if (defaultValue != null) {
      walk.textOf(defaultValue.loc)
    } else {
      null
    };
    out.push(new DocParam(param.name.name, walk.ref(param.typeAnnotation),
        param.optional, fallback));
  }
  return out;
}

function parameterText(params: GrowableArray<DocParam>): String {
  let sb = new StringBuilder(48);
  sb.append('(');
  var i = 0;
  while (i < params.length) {
    if (i > 0) {
      sb.append(', ');
    }
    let param = params[i];
    let fallback = param.defaultValue;
    sb.append(param.name);
    // A default already says the parameter is optional; `b?: i32 = 1`
    // is not how the source spells it.
    if (param.optional && fallback == null) {
      sb.append('?');
    }
    let type = param.type;
    if (type != null) {
      sb.append(': ');
      sb.append(type.text);
    }
    if (fallback != null) {
      sb.append(' = ');
      sb.append(fallback);
    }
    i += 1;
  }
  sb.append(')');
  return sb.toString();
}

function returnText(returns: TypeRef | null): String {
  if (returns == null) {
    return '';
  }
  return ': ' + returns.text;
}

function caseParamText(walk: Walk, params: Array<CaseClassParam>): String {
  let sb = new StringBuilder(48);
  var i = 0;
  while (i < params.length) {
    if (i > 0) {
      sb.append(', ');
    }
    let param = params[i];
    let mutability = param.mutability;
    if (mutability != null) {
      sb.append(mutability);
      sb.append(' ');
    }
    sb.append(param.name.name);
    sb.append(': ');
    sb.append(annotationText(param.typeAnnotation));
    let defaultValue = param.defaultValue;
    if (defaultValue != null) {
      let fallback = walk.textOf(defaultValue.loc);
      if (fallback != null) {
        sb.append(' = ');
        sb.append(fallback);
      }
    }
    i += 1;
  }
  return sb.toString();
}

function annotationList(annotations: Array<TypeAnnotation>): String {
  let sb = new StringBuilder(32);
  var i = 0;
  while (i < annotations.length) {
    if (i > 0) {
      sb.append(', ');
    }
    sb.append(annotationText(annotations[i]));
    i += 1;
  }
  return sb.toString();
}

/** The name a member's name node spells, or null for a symbol name. */
function memberName(node: Node): String | null {
  return match (node) {
  case Identifier as id: id.name
  case IdentifierPattern as pattern: pattern.name
  case SymbolPropertyName {}: null
  case _: null
};
}

function patternName(node: Node): String | null {
  return match (node) {
  case IdentifierPattern as pattern: pattern.name
  case Identifier as id: id.name
  case _: null
};
}

/** The arrow function a `let` binds, if it binds one directly. */
function arrowOf(decl: VariableDeclaration): FunctionExpression | null {
  return match (decl.init) {
  case FunctionExpression as fn: fn
  case _: null
};
}

function nodeType(walk: Walk, node: Node): Type | null {
  let model = walk.model;
  if (model == null) {
    return null;
  }
  return model.getNodeType(node);
}

function isOperatorName(name: String): boolean {
  if (name.length == 0) {
    return false;
  }
  let b = name.getByteAt(0);
  let isLetter = (b >= 65 && b <= 90) || (b >= 97 && b <= 122);
  return !isLetter && b != 35;
}
  • 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