/** * 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) /** 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; /** `#.`. */ 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(0); var parameters = new Array(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; /** `#`. */ 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(0); var typeParameters = new Array(0); /** Parameters, for functions and variables holding a function. */ var parameters = new Array(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(0); var mixins = new Array(0); var members = new Array(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, /** 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 `.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(0); var reexports = new Array(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(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 == '') { 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(); /** 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)}`; } }