@gtkx/codegen 1.0.0-rc.3 → 1.0.0-rc.4

package/src/analysis/descriptor-render.ts

@@ -51,11 +51,9 @@ import {
 
 type RenderDescriptorOptions = {
     argIndexOffset?: number;
-    /** GIR parameter index to emitted argument index, for callables that drop parameters. */
     argIndexMap?: Map<number, number> | undefined;
-    callerAllocated?: boolean;
+    isCallerAllocated?: boolean;
     isInline?: boolean;
-    /** Set on the return value of a callable with no instance parameter, which creates what it returns. */
     isNewlyCreated?: boolean;
 };
 
@@ -76,7 +74,7 @@ type FundamentalDescriptor = {
     typeName: string | undefined;
     ownership: Ownership;
     wrapperClass?: string | undefined;
-    inline?: boolean | undefined;
+    isInline?: boolean | undefined;
 };
 
 type AncestorFundamental = {
@@ -94,7 +92,7 @@ type FundamentalRecordOptions = {
     unrefFunc: string;
     ownership: Ownership;
     wrapperClass: string | undefined;
-    inline: boolean;
+    isInline: boolean;
 };
 
 const LIST_HELPERS: Record<Exclude<ListFlavor, "gbytearray">, ListDescriptorName> = {
@@ -104,17 +102,8 @@ const LIST_HELPERS: Record<Exclude<ListFlavor, "gbytearray">, ListDescriptorName
     garray: "gArray",
 };
 
-/**
- * `glib:type-name` of every fundamental whose instances are born with a floating reference, so a
- * callable that creates one hands back a claim nobody has taken rather than an owned reference.
- * GIR annotates those returns `transfer-ownership="full"` all the same, so the annotation alone
- * cannot tell them apart from a genuinely owned return such as `g_param_spec_ref`.
- */
 const FLOATING_FUNDAMENTALS: Set<string> = new Set(["GParam"]);
 
-// A callable that drops parameters (varargs, and the closure/destroy slots folded into a callback)
-// shifts every later parameter left, so a GIR length index has to be looked up in the emitted list
-// rather than shifted by the instance offset alone.
 const mapArgIndex = (options: ArgIndexOptions, girIndex: number): number =>
     options.argIndexMap?.get(girIndex) ?? girIndex + options.argIndexOffset;
 
@@ -175,9 +164,6 @@ const renderDescriptor = (
         case "varargs": {
             return tVoid;
         }
-        // A callback in a slot no `renderCallbackType` covers (a vtable entry, a signal argument, a
-        // record field) is still a function pointer occupying a pointer-sized slot. `t.void` would
-        // hand the implementation `undefined` where the pointer belongs.
         case "callback": {
             return tUint64;
         }
@@ -288,13 +274,10 @@ const renderParamDescriptor = (
 
     return renderDescriptor(context, ref, parameter.transferOwnership, {
         ...argIndex,
-        callerAllocated: isCallerAllocatedOut(parameter) || isRecordInout(context, parameter),
+        isCallerAllocated: isCallerAllocatedOut(parameter) || isRecordInout(context, parameter),
     });
 };
 
-// `closure=` on a callback's own parameter states which slot carries the user data, and it is what
-// the TypeScript signature already goes by. The name scan stays as a fallback: 88 callbacks across
-// the installed GIRs carry no `closure=` at all.
 const userDataIndexByName = (parameters: GirParameter[]): number | undefined => {
     let userDataIndex: number | undefined;
 
@@ -379,19 +362,16 @@ const primitiveExpression = (category: PrimitiveCategory, ownership: Ownership):
 };
 
 const renderFundamental = (descriptor: FundamentalDescriptor): string => {
-    const { lib, refFunc, unrefFunc, typeName, ownership, wrapperClass, inline } = descriptor;
+    const { lib, refFunc, unrefFunc, typeName, ownership, wrapperClass, isInline } = descriptor;
 
     return tFundamental(lib, refFunc, unrefFunc, {
         ownership,
         typeName,
         wrapperClass,
-        inline,
+        isInline,
     });
 };
 
-// A freshly created floating instance is claimed by sinking it, which is what the fundamental's
-// declared ref function does, so it is marshalled as transfer-none: adopting the floating reference
-// instead would leave the handle releasing a claim it never took.
 const sunkOwnership = (
     ancestor: AncestorFundamental,
     ownership: Ownership,
@@ -404,8 +384,6 @@ const sunkOwnership = (
     return FLOATING_FUNDAMENTALS.has(ancestor.typeName) ? "borrowed" : ownership;
 };
 
-// GIR marks only the root of a fundamental hierarchy with `glib:fundamental` and its ref/unref pair,
-// so a derived type such as GtkPropertyExpression carries neither and has to inherit both.
 const classOrInterfaceExpression = (
     context: ModuleContext,
     resolved: Extract<EntityType, { kind: "class" | "interface" }>,
@@ -510,9 +488,6 @@ const renderSelfDescriptor = (context: ModuleContext, instance: GirParameter): s
     return tObject("borrowed");
 };
 
-// A record expresses its acquire/release pair as `copy-function`/`free-function`: no `<record>` in
-// any installed GIR carries `glib:ref-func`, and GVariant's copy function really is
-// `g_variant_ref_sink`.
 const recordRefPair = (record: ResolvedRecord): { refFunc: string | undefined; unrefFunc: string | undefined } => ({
     refFunc: record.glibRefFunc ?? record.copyFunc,
     unrefFunc: record.glibUnrefFunc ?? record.freeFunc,
@@ -532,7 +507,7 @@ const structExpression = (
     context: ModuleContext,
     resolved: Extract<EntityType, { kind: "record" }>,
     ownership: Ownership,
-    options: { callerAllocated: boolean; inline: boolean },
+    options: { isCallerAllocated: boolean; isInline: boolean },
 ): string => {
     const { size } = computeRecordFieldSlots(context, resolved.value.fields, resolved.value.isUnion);
     const wrapperClass = context.qualify(resolved.namespace.name, resolved.value.name);
@@ -541,13 +516,13 @@ const structExpression = (
     return tStruct(ownership, {
         size: isCopyable && size > 0 ? size : undefined,
         wrapperClass,
-        callerAllocated: options.callerAllocated,
-        inline: options.inline,
+        isCallerAllocated: options.isCallerAllocated,
+        isInline: options.isInline,
     });
 };
 
 const fundamentalRecordExpression = (options: FundamentalRecordOptions): string => {
-    const { resolved, refFunc, unrefFunc, ownership, wrapperClass, inline } = options;
+    const { resolved, refFunc, unrefFunc, ownership, wrapperClass, isInline } = options;
 
     return renderFundamental({
         lib: resolved.namespace.sharedLibrary ?? "",
@@ -556,7 +531,7 @@ const fundamentalRecordExpression = (options: FundamentalRecordOptions): string
         typeName: resolved.value.glibTypeName,
         ownership,
         wrapperClass,
-        inline,
+        isInline,
     });
 };
 
@@ -564,11 +539,11 @@ const boxedRecordExpression = (options: {
     context: ModuleContext;
     resolved: Extract<EntityType, { kind: "record" }>;
     ownership: Ownership;
-    callerAllocated: boolean;
-    inline: boolean;
+    isCallerAllocated: boolean;
+    isInline: boolean;
     typeFnName: string;
 }): string => {
-    const { context, resolved, ownership, callerAllocated, inline, typeFnName } = options;
+    const { context, resolved, ownership, isCallerAllocated, isInline, typeFnName } = options;
     const record = resolved.value;
     const glibName = record.glibTypeName ?? record.cType ?? record.name;
     const { size } = computeRecordFieldSlots(context, record.fields, record.isUnion);
@@ -577,8 +552,8 @@ const boxedRecordExpression = (options: {
         ownership,
         sharedLibrary: resolved.namespace.sharedLibrary,
         getTypeFnName: typeFnName,
-        callerAllocated,
-        inline,
+        isCallerAllocated,
+        isInline,
         size: size > 0 ? size : undefined,
     });
 };
@@ -592,8 +567,8 @@ const plainRecordExpression = (
     const record = resolved.value;
 
     const layout = {
-        callerAllocated: placement.isCallerAllocated ?? false,
-        inline: placement.isInline ?? false,
+        isCallerAllocated: placement.isCallerAllocated ?? false,
+        isInline: placement.isInline ?? false,
     };
 
     if (record.glibGetType === undefined) {
@@ -623,7 +598,7 @@ const recordExpression = (
             unrefFunc,
             ownership,
             wrapperClass,
-            inline: placement.isInline ?? false,
+            isInline: placement.isInline ?? false,
         });
     }
 
@@ -660,7 +635,7 @@ const expressionForResolved = (
         }
         case "record": {
             return recordExpression(context, resolved, ownership, {
-                isCallerAllocated: options.callerAllocated ?? false,
+                isCallerAllocated: options.isCallerAllocated ?? false,
                 isInline: options.isInline ?? false,
             });
         }

package/src/analysis/descriptor.ts

@@ -64,23 +64,23 @@ type BoxedOptions = {
     ownership: Ownership;
     sharedLibrary: string | undefined;
     getTypeFnName: string;
-    callerAllocated: boolean;
-    inline?: boolean;
+    isCallerAllocated: boolean;
+    isInline?: boolean;
     size: number | undefined;
 };
 
 type StructOptions = {
     size: number | string | undefined;
     wrapperClass: string | undefined;
-    callerAllocated: boolean;
-    inline?: boolean;
+    isCallerAllocated: boolean;
+    isInline?: boolean;
 };
 
 type FundamentalOptions = {
     ownership: Ownership;
     typeName: string | undefined;
     wrapperClass: string | undefined;
-    inline?: boolean | undefined;
+    isInline?: boolean | undefined;
 };
 
 type ListDescriptorName = "list" | "slist" | "ptrArray" | "gArray";
@@ -165,8 +165,8 @@ const tBoxed = (glibName: string, options: BoxedOptions): string =>
                 ? undefined
                 : `sharedLibrary: ${sourceStringLiteral(options.sharedLibrary)}`,
             `getTypeFnName: ${sourceStringLiteral(options.getTypeFnName)}`,
-            options.callerAllocated ? "callerAllocated: true" : undefined,
-            options.inline === true ? "inline: true" : undefined,
+            options.isCallerAllocated ? "isCallerAllocated: true" : undefined,
+            options.isInline === true ? "isInline: true" : undefined,
             options.size === undefined ? undefined : `size: ${String(options.size)}`,
         ]),
     ]);
@@ -177,13 +177,13 @@ const tStruct = (ownership: Ownership, options: StructOptions): string =>
         optionsObject([
             options.size === undefined ? undefined : `size: ${String(options.size)}`,
             options.wrapperClass === undefined ? undefined : `wrapperClass: ${options.wrapperClass}`,
-            options.callerAllocated ? "callerAllocated: true" : undefined,
-            options.inline === true ? "inline: true" : undefined,
+            options.isCallerAllocated ? "isCallerAllocated: true" : undefined,
+            options.isInline === true ? "isInline: true" : undefined,
         ]),
     ]);
 
 const tInlineStruct = (): string =>
-    tStruct("borrowed", { size: undefined, wrapperClass: undefined, callerAllocated: false });
+    tStruct("borrowed", { size: undefined, wrapperClass: undefined, isCallerAllocated: false });
 
 const tFundamental = (lib: string, refFunc: string, unrefFunc: string, options: FundamentalOptions): string =>
     call("fundamental", [
@@ -194,7 +194,7 @@ const tFundamental = (lib: string, refFunc: string, unrefFunc: string, options:
             `ownership: ${sourceStringLiteral(options.ownership)}`,
             options.typeName === undefined ? undefined : `typeName: ${sourceStringLiteral(options.typeName)}`,
             options.wrapperClass === undefined ? undefined : `wrapperClass: ${options.wrapperClass}`,
-            options.inline === true ? "inline: true" : undefined,
+            options.isInline === true ? "isInline: true" : undefined,
         ]),
     ]);
 
@@ -252,9 +252,9 @@ const tBind = (args: BindArgs): string =>
 const tFn = (
     lib: string,
     cIdentifier: string,
-    spec: { args: string; returns: string; throws: boolean },
+    spec: { args: string; returns: string; canThrow: boolean },
 ): string => {
-    const throwsEntry = spec.throws ? ", throws: true" : "";
+    const throwsEntry = spec.canThrow ? ", canThrow: true" : "";
 
     return call("fn", [
         sourceStringLiteral(lib),

package/src/analysis/param-structure.ts

@@ -14,8 +14,8 @@ type HandlerResultOptions = {
     library: Library;
     signal: GirCallable;
     renderType: (ref: TypeId | undefined, isNullable: boolean) => string;
-    includeCallerAllocated: boolean;
-    optOut: boolean;
+    shouldIncludeCallerAllocated: boolean;
+    isOptOut: boolean;
 };
 
 const isInputParameter = (options: {
@@ -75,8 +75,6 @@ const closureAndDestroyIndices = (fn: GirFunction): Set<number> => {
     return indices;
 };
 
-// The emitted argument list is the instance parameter followed by every parameter `planParameter`
-// keeps, so a GIR index only lines up with an emitted index when nothing before it was dropped.
 const emittedArgIndices = (fn: GirFunction, instanceOffset: number): Map<number, number> => {
     const closureIndices = closureAndDestroyIndices(fn);
     const map: Map<number, number> = new Map();
@@ -199,9 +197,9 @@ const foldOutParamShape = (primary: string | undefined, outTypes: string[]): str
 const isHandlerOutParameter = (options: {
     library: Library;
     parameter: GirParameter;
-    includeCallerAllocated: boolean;
+    shouldIncludeCallerAllocated: boolean;
 }): boolean => {
-    const { library, parameter, includeCallerAllocated } = options;
+    const { library, parameter, shouldIncludeCallerAllocated } = options;
 
     if (parameter.isVarargs) {
         return false;
@@ -215,7 +213,7 @@ const isHandlerOutParameter = (options: {
         return true;
     }
 
-    return includeCallerAllocated && isCallerAllocatedOut(parameter);
+    return shouldIncludeCallerAllocated && isCallerAllocatedOut(parameter);
 };
 
 const scalarResultType = (primary: string | undefined, isOptOut: boolean): string => {
@@ -227,18 +225,18 @@ const scalarResultType = (primary: string | undefined, isOptOut: boolean): strin
 };
 
 const renderHandlerResultType = (options: HandlerResultOptions): string => {
-    const { library, signal, renderType, includeCallerAllocated, optOut } = options;
+    const { library, signal, renderType, shouldIncludeCallerAllocated, isOptOut } = options;
 
     const primary = shouldOmitPrimaryReturn(library, signal.returnValue)
         ? undefined
         : renderType(signal.returnValue.type, signal.returnValue.nullable);
 
     const outTypes = signal.parameters
-        .filter((parameter) => isHandlerOutParameter({ library, parameter, includeCallerAllocated }))
+        .filter((parameter) => isHandlerOutParameter({ library, parameter, shouldIncludeCallerAllocated }))
         .map((parameter) => renderType(parameter.type, parameter.nullable));
 
     if (outTypes.length === 0) {
-        return scalarResultType(primary, optOut);
+        return scalarResultType(primary, isOptOut);
     }
 
     return foldOutParamShape(primary, outTypes);

package/src/analysis/ts-type.ts

@@ -19,7 +19,7 @@ type ReferenceName = {
 type TsTypeTarget = {
     containerStyle: "map" | "record";
     callbackType: string;
-    byteArrayAsNumber: boolean;
+    shouldRenderByteArrayAsNumber: boolean;
     renderNamed: (resolved: GirType | undefined, name: ReferenceName) => string;
     renderGtype: () => string;
 };
@@ -100,10 +100,8 @@ const renderContainerType = (
     return renderSequenceType(library, target, type);
 };
 
-// An array whose length nothing states decodes as the bare pointer it is, so its TypeScript type has
-// to say so too rather than promising elements nothing can count.
 const renderSequenceType = (library: Library, target: TsTypeTarget, type: CArrayType | ListType): string => {
-    if (type.kind === "list" && type.flavor === "gbytearray" && target.byteArrayAsNumber) {
+    if (type.kind === "list" && type.flavor === "gbytearray" && target.shouldRenderByteArrayAsNumber) {
         return "number[]";
     }
 
@@ -129,7 +127,7 @@ const renderNamedType = (
 const moduleTarget = (context: ModuleContext): TsTypeTarget => ({
     containerStyle: "map",
     callbackType: "((...args: any[]) => any)",
-    byteArrayAsNumber: true,
+    shouldRenderByteArrayAsNumber: true,
     renderNamed: (_resolved, name) => context.qualify(name.namespaceName, name.typeName),
     renderGtype: () => gtypeTsType(context),
 });
@@ -148,7 +146,7 @@ const recordTypeTarget = (
     const target: TsTypeTarget = {
         containerStyle: "record",
         callbackType: "((...args: unknown[]) => unknown)",
-        byteArrayAsNumber: false,
+        shouldRenderByteArrayAsNumber: false,
         renderNamed: (resolved, name) => {
             if (resolved?.kind === "alias") {
                 return resolved.value.target === undefined

package/src/compile.ts

@@ -29,8 +29,10 @@ const BASE_COMPILER_OPTIONS = {
     noImplicitReturns: true,
     noFallthroughCasesInSwitch: true,
     allowUnreachableCode: false,
+    allowImportingTsExtensions: true,
     forceConsistentCasingInFileNames: true,
     resolveJsonModule: true,
+    rewriteRelativeImportExtensions: true,
     skipLibCheck: true,
     types: ["node"],
 };
@@ -47,7 +49,6 @@ const FORMAT_HOST: ts.FormatDiagnosticsHost = {
     getNewLine: () => "\n",
 };
 
-/** `@gtkx/codegen`'s own `node_modules`, which has `@types/node` plus the `@gtkx/*` deps the store typecheck needs. */
 const codegenModules = (): string => {
     const sourceDir = dirname(fileURLToPath(import.meta.url));
 

package/src/docs/api-reference.ts

@@ -6,41 +6,90 @@ import { Library } from "../gir/library.js";
 import { type GirNamespace, namespaceDirectory } from "../gir/namespace.js";
 import { dedupeCallables, isEmittableCallable } from "../store/gi/callables.js";
 import { namespaceFunctionExportName } from "../store/gi/function.js";
+import { type ElementProps, setElementProps } from "../store/jsx/element-prop-imports.js";
 import { collectIntrinsicElementClasses, type GlibNamedClass } from "../store/jsx/intrinsic-elements.js";
+import { type OmittedProps, setOmittedProps } from "../store/jsx/omitted-props.js";
 import { createElementPageContext, type ElementPageContext, renderElementPage } from "./element-page.js";
 import { docsSignatureContext, firstSentence, namespaceOrder } from "./render.js";
 import { type GiSymbolEntry, renderSymbolPage, type SymbolPageOptions } from "./symbol-page.js";
 
+/** What to index and the element config the rendered pages reflect. */
 type ApiReferenceOptions = {
+    /** GIR library identifiers to load, such as `"Gtk-4.0"`; their dependencies are pulled in too. */
     libraries: string[];
+    /** Directories to search for `.gir` files. */
     girPath: string[];
+    /** Base props interfaces per element, as read by `readBuiltinElements`; without it pages miss them. */
+    props?: ElementProps;
+    /** GObject properties the project omits from generated props; without it pages show props that do not exist. */
+    omittedProps?: OmittedProps;
 };
 
+/** Narrows an `ApiReference.symbols` enumeration. */
+type ApiSymbolQuery = {
+    /** GIR namespace to keep, matched case-insensitively; every namespace when omitted. */
+    namespace?: string;
+    /** Symbol kinds to keep; every kind when omitted. */
+    kinds?: ApiSymbolKind[];
+};
+
+/** What an indexed symbol is: one of the GIR symbol kinds, or a JSX element. */
 type ApiSymbolKind = GiSymbolEntry["kind"] | "element";
 
+/** An indexed symbol, without its reference page. */
 type ApiSymbol = {
+    /** GIR namespace declaring the symbol, such as `"Gtk"`. */
     namespace: string;
+    /** Name within the namespace, which for an element is its GLib type name. */
     name: string;
+    /** Kind the reference groups and filters the symbol by, `"element"` for a JSX tag. */
     kind: ApiSymbolKind;
+    /** First sentence of the symbol's GIR documentation, elided past 220 characters and empty when it has none. */
     summary: string;
 };
 
+/** How much of one namespace the reference indexes. */
 type ApiNamespaceSummary = {
+    /** GIR namespace name, such as `"Gtk"`. */
     name: string;
+    /** The `@gtkx/gi` subpath the namespace's symbols are imported from. */
     importPath: string;
+    /** How many symbols other than JSX elements the namespace contributes. */
     symbols: number;
+    /** How many JSX elements the namespace contributes. */
     elements: number;
 };
 
+/** What an `ApiReference.lookup` found: a rendered page, several candidates for the name, or nothing. */
 type ApiLookupResult =
-    | { outcome: "page"; symbol: ApiSymbol; markdown: string } |
-    { outcome: "ambiguous"; candidates: ApiSymbol[] } |
-    { outcome: "notFound" };
-
+    | {
+        /** Discriminant selecting the variant. */
+        outcome: "page";
+        /** Index entry for the symbol the query resolved to. */
+        symbol: ApiSymbol;
+        /** The symbol's complete reference page, rendered as Markdown. */
+        markdown: string;
+    } |
+    {
+        /** Discriminant selecting the variant. */
+        outcome: "ambiguous";
+        /** Every symbol the name answers to, to be narrowed by namespace or kind. */
+        candidates: ApiSymbol[];
+    } |
+    {
+        /** Discriminant selecting the variant. */
+        outcome: "notFound";
+    };
+
+/** A fuzzy search over indexed symbol names. */
 type ApiSearchOptions = {
+    /** Text matched case-insensitively against each symbol's name and its qualified `Namespace.Name` form. */
     query: string;
+    /** GIR namespace to keep, matched case-insensitively; every namespace when omitted. */
     namespace?: string;
+    /** Symbol kinds to keep; every kind when omitted. */
     kinds?: ApiSymbolKind[];
+    /** Maximum number of results, 20 by default. */
     limit?: number;
 };
 
@@ -55,6 +104,7 @@ type ElementEntry = {
 type SymbolEntry = GiSymbolEntry | ElementEntry;
 type ScoredEntry = { score: number; entry: SymbolEntry };
 
+/** Every kind the reference indexes, in the order a namespace overview groups its symbols. */
 const API_SYMBOL_KINDS: ApiSymbolKind[] = [
     "element",
     "class",
@@ -89,6 +139,32 @@ const compareNames = (a: string, b: string): number => {
     return a > b ? 1 : 0;
 };
 
+const isQueriedEntry = (
+    entry: SymbolEntry,
+    namespaceFilter: string | undefined,
+    kinds: Set<ApiSymbolKind> | undefined,
+): boolean => {
+    if (namespaceFilter !== undefined && entry.namespace.name.toLowerCase() !== namespaceFilter) {
+        return false;
+    }
+
+    return kinds === undefined || kinds.has(entry.kind);
+};
+
+const compareApiSymbols = (a: ApiSymbol, b: ApiSymbol): number => {
+    const byNamespace = namespaceOrder(a.namespace).localeCompare(namespaceOrder(b.namespace));
+
+    return byNamespace === 0 ? a.name.localeCompare(b.name) : byNamespace;
+};
+
+/**
+ * Loads the GIR data for the given libraries and indexes every symbol and JSX element in it. The result is
+ * a read-only view: it generates no store and needs none, so a tool can explore the bindings a project would
+ * get without running codegen.
+ *
+ * @param options Which libraries to index, where to find them, and the project's element config.
+ * @returns The indexed reference.
+ */
 const loadApiReference = (options: ApiReferenceOptions): ApiReference => new ApiReference(options);
 
 const functionEntry = (
@@ -265,6 +341,7 @@ const searchScore = (entry: SymbolEntry, query: string): number => {
     return 0;
 };
 
+/** An index over the GIR data a project's bindings are generated from, queryable and renderable as Markdown. */
 class ApiReference {
     private library: Library;
     private libraries: string[];
@@ -275,13 +352,23 @@ class ApiReference {
     private byNamespace: Map<string, SymbolEntry[]> = new Map();
     private elementsByClass: Map<string, string> = new Map();
 
+    private props: ElementProps;
+    private omittedProps: OmittedProps;
+
     constructor(options: ApiReferenceOptions) {
         this.libraries = options.libraries;
+        this.props = options.props ?? {};
+        this.omittedProps = options.omittedProps ?? {};
         this.library = Library.load(options.libraries, options.girPath);
         this.elementContext = createElementPageContext(this.library, (): string | undefined => undefined);
         this.buildIndex();
     }
 
+    private applyElementConfig(): void {
+        setElementProps(this.props);
+        setOmittedProps(this.omittedProps);
+    }
+
     private add(entry: SymbolEntry): void {
         this.entries.push(entry);
 
@@ -362,6 +449,8 @@ class ApiReference {
 
     private renderPage(entry: SymbolEntry): string {
         if (entry.kind === "element") {
+            this.applyElementConfig();
+
             return renderElementPage(entry.element, this.elementContext);
         }
 
@@ -410,10 +499,18 @@ class ApiReference {
         return scored;
     }
 
+    /** Paths of the `.gir` files the index was built from, including the ones pulled in as dependencies. */
     get girFiles(): string[] {
         return this.library.girFiles;
     }
 
+    /**
+     * Resolves a name to a single symbol and renders its reference page. The name may be bare (`Button`) or
+     * qualified (`Gtk.Button`), and is matched case-insensitively; a name several symbols answer to is
+     * reported as ambiguous rather than picked between.
+     *
+     * @param kind Restricts the match to one kind, which is how a class and its JSX element are told apart.
+     */
     lookup(query: string, kind?: ApiSymbolKind): ApiLookupResult {
         const trimmed = query.trim();
 
@@ -435,6 +532,21 @@ class ApiReference {
         return { outcome: "page", symbol: this.toApiSymbol(entry), markdown: this.renderPage(entry) };
     }
 
+    /** Every indexed symbol the query keeps, ordered by namespace (Gtk, then Adw, then alphabetically) and name. */
+    symbols(query: ApiSymbolQuery = {}): ApiSymbol[] {
+        const namespaceFilter = query.namespace?.toLowerCase();
+        const kinds = query.kinds === undefined ? undefined : new Set(query.kinds);
+
+        return this.entries
+            .filter((entry) => isQueriedEntry(entry, namespaceFilter, kinds))
+            .map((entry) => this.toApiSymbol(entry))
+            .toSorted(compareApiSymbols);
+    }
+
+    /**
+     * Symbols whose name matches the query, best first: an exact name beats a prefix, which beats a
+     * substring, and shorter names win ties. An empty query matches nothing.
+     */
     search(options: ApiSearchOptions): ApiSymbol[] {
         const query = options.query.trim().toLowerCase();
 
@@ -450,6 +562,7 @@ class ApiReference {
         return scored.slice(0, limit).map((item) => this.toApiSymbol(item.entry));
     }
 
+    /** A summary of every indexed namespace, ordered Gtk, Adw, then alphabetically. */
     namespaces(): ApiNamespaceSummary[] {
         const summaries = [...this.byNamespace].map(([name, entries]) => ({
             name,
@@ -461,6 +574,10 @@ class ApiReference {
         return sortStringsBy(summaries, (summary) => namespaceOrder(summary.name));
     }
 
+    /**
+     * Sorted names of everything a namespace contributes, JSX elements included. The namespace is matched
+     * case-insensitively, and an unindexed one yields an empty array.
+     */
     symbolNames(namespaceName: string): string[] {
         const namespace = this.findNamespace(namespaceName);
 
@@ -473,6 +590,7 @@ class ApiReference {
         return sortStrings(entries.map((entry) => entry.name));
     }
 
+    /** Renders the reference's Markdown landing page: every namespace, its import path, and its totals. */
     overview(): string {
         const rows = this.namespaces().map(
             (summary) =>
@@ -500,6 +618,10 @@ class ApiReference {
         ].join("\n");
     }
 
+    /**
+     * Renders one namespace's Markdown page: its import line and its symbol names grouped by kind. The
+     * namespace is matched case-insensitively, and an unindexed one yields undefined.
+     */
     namespaceOverview(name: string): string | undefined {
         const namespace = this.findNamespace(name);
 
@@ -549,4 +671,5 @@ export {
     type ApiNamespaceSummary,
     type ApiLookupResult,
     type ApiSearchOptions,
+    type ApiSymbolQuery,
 };