typedoc/dist/lib/converter/converter.d.ts

import ts from "typescript";
import type { Application } from "../application.js";
import { Comment, type CommentDisplayPart, type ContainerReflection, type DeclarationReflection, DocumentReflection, type ParameterReflection, ProjectReflection, type Reflection, type ReflectionSymbolId, type SignatureReflection, type SomeType, type TypeParameterReflection } from "../models/index.js";
import { Context } from "./context.js";
import { AbstractComponent } from "../utils/component.js";
import { MinimalSourceFile } from "../utils/index.js";
import type { DocumentationEntryPoint } from "../utils/entry-point.js";
import type { CommentParserConfig } from "./comments/index.js";
import type { CommentStyle, ValidationOptions } from "../utils/options/declaration.js";
import { type ExternalSymbolResolver, type ExternalResolveResult } from "./comments/linkResolver.js";
import { type DeclarationReference } from "./comments/declarationReference.js";
import type { FileRegistry } from "../models/FileRegistry.js";
import { IncludePlugin } from "./plugins/IncludePlugin.js";
export interface ConverterEvents {
    begin: [Context];
    end: [Context];
    createProject: [Context, ProjectReflection];
    createDeclaration: [Context, DeclarationReflection];
    createDocument: [undefined, DocumentReflection];
    createSignature: [
        Context,
        SignatureReflection,
        (ts.SignatureDeclaration | ts.IndexSignatureDeclaration | ts.JSDocSignature)?,
        ts.Signature?
    ];
    createParameter: [Context, ParameterReflection, ts.Node?];
    createTypeParameter: [
        Context,
        TypeParameterReflection,
        ts.TypeParameterDeclaration?
    ];
    resolveBegin: [Context];
    resolveReflection: [Context, Reflection];
    resolveEnd: [Context];
}
/**
 * Compiles source files using TypeScript and converts compiler symbols to reflections.
 *
 * @group Common
 * @summary Responsible for converting TypeScript symbols into {@link Reflection}s and {@link Type}s.
 */
export declare class Converter extends AbstractComponent<Application, ConverterEvents> {
    /** @internal */
    accessor externalPattern: string[];
    private externalPatternCache?;
    private excludeCache?;
    /** @internal */
    accessor excludeExternals: boolean;
    /** @internal */
    accessor excludeNotDocumented: boolean;
    /** @internal */
    accessor excludePrivate: boolean;
    /** @internal */
    accessor excludeProtected: boolean;
    /** @internal */
    accessor excludeReferences: boolean;
    /** @internal */
    accessor commentStyle: CommentStyle;
    /** @internal */
    accessor validation: ValidationOptions;
    /** @internal */
    accessor externalSymbolLinkMappings: Record<string, Record<string, string>>;
    /** @internal */
    accessor preserveLinkText: boolean;
    /** @internal */
    accessor maxTypeConversionDepth: number;
    private _config?;
    private _externalSymbolResolvers;
    get config(): CommentParserConfig;
    /**
     * General events
     */
    /**
     * Triggered when the converter begins converting a project.
     * The listener will be given a {@link Context} object.
     * @event
     */
    static readonly EVENT_BEGIN: "begin";
    /**
     * Triggered when the converter has finished converting a project.
     * The listener will be given a {@link Context} object.
     * @event
     */
    static readonly EVENT_END: "end";
    /**
     * Factory events
     */
    /**
     * Triggered when the converter has created a project reflection.
     * The listener will be given {@link Context} and a {@link Models.ProjectReflection}.
     * @event
     */
    static readonly EVENT_CREATE_PROJECT: "createProject";
    /**
     * Triggered when the converter has created a declaration reflection.
     * The listener will be given {@link Context} and a {@link Models.DeclarationReflection}.
     * @event
     */
    static readonly EVENT_CREATE_DECLARATION: "createDeclaration";
    /**
     * Triggered when the converter has created a document reflection.
     * The listener will be given `undefined` (for consistency with the
     * other create events) and a {@link Models.DocumentReflection}.
     * @event
     */
    static readonly EVENT_CREATE_DOCUMENT: "createDocument";
    /**
     * Triggered when the converter has created a signature reflection.
     * The listener will be given {@link Context}, {@link Models.SignatureReflection} | {@link Models.ProjectReflection} the declaration,
     * `ts.SignatureDeclaration | ts.IndexSignatureDeclaration | ts.JSDocSignature | undefined`,
     * and `ts.Signature | undefined`. The signature will be undefined if the created signature is an index signature.
     * @event
     */
    static readonly EVENT_CREATE_SIGNATURE: "createSignature";
    /**
     * Triggered when the converter has created a parameter reflection.
     * The listener will be given {@link Context}, {@link Models.ParameterReflection} and a `ts.Node?`
     * @event
     */
    static readonly EVENT_CREATE_PARAMETER: "createParameter";
    /**
     * Triggered when the converter has created a type parameter reflection.
     * The listener will be given {@link Context} and a {@link Models.TypeParameterReflection}
     * @event
     */
    static readonly EVENT_CREATE_TYPE_PARAMETER: "createTypeParameter";
    /**
     * Resolve events
     */
    /**
     * Triggered when the converter begins resolving a project.
     * The listener will be given {@link Context}.
     * @event
     */
    static readonly EVENT_RESOLVE_BEGIN: "resolveBegin";
    /**
     * Triggered when the converter resolves a reflection.
     * The listener will be given {@link Context} and a {@link Reflection}.
     * @event
     */
    static readonly EVENT_RESOLVE: "resolveReflection";
    /**
     * Triggered when the converter has finished resolving a project.
     * The listener will be given {@link Context}.
     * @event
     */
    static readonly EVENT_RESOLVE_END: "resolveEnd";
    /** @internal @hidden */
    includePlugin: IncludePlugin;
    constructor(owner: Application);
    /**
     * Compile the given source files and create a project reflection for them.
     */
    convert(entryPoints: readonly DocumentationEntryPoint[]): ProjectReflection;
    /** @internal */
    addProjectDocuments(project: ProjectReflection): void;
    /** @internal */
    convertSymbol(context: Context, symbol: ts.Symbol, exportSymbol?: ts.Symbol): void;
    /**
     * Convert the given TypeScript type into its TypeDoc type reflection.
     *
     * @param context  The context object describing the current state the converter is in.
     * @returns The TypeDoc type reflection representing the given node and type.
     * @internal
     */
    convertType(context: Context, node: ts.TypeNode | ts.Type | undefined): SomeType;
    /**
     * Parse the given file into a comment. Intended to be used with markdown files.
     */
    parseRawComment(file: MinimalSourceFile, files: FileRegistry): {
        content: CommentDisplayPart[];
        frontmatter: Record<string, unknown>;
    };
    /**
     * Adds a new resolver that the theme can use to try to figure out how to link to a symbol declared
     * by a third-party library which is not included in the documentation.
     *
     * The resolver function will be passed a declaration reference which it can attempt to resolve. If
     * resolution fails, the function should return undefined.
     *
     * Note: This will be used for both references to types declared in node_modules (in which case the
     * reference passed will have the `moduleSource` set and the `symbolReference` will navigate via `.`)
     * and user defined \{\@link\} tags which cannot be resolved. If the link being resolved is inferred
     * from a type, then no `part` will be passed to the resolver function.
     */
    addUnknownSymbolResolver(resolver: ExternalSymbolResolver): void;
    /** @internal */
    resolveExternalLink(ref: DeclarationReference, refl: Reflection, part: CommentDisplayPart | undefined, symbolId: ReflectionSymbolId | undefined): ExternalResolveResult | string | undefined;
    resolveLinks(comment: Comment, owner: Reflection): void;
    resolveLinks(parts: readonly CommentDisplayPart[], owner: Reflection): CommentDisplayPart[];
    /**
     * Compile the files within the given context and convert the compiler symbols to reflections.
     *
     * @param context  The context object describing the current state the converter is in.
     * @returns An array containing all errors generated by the TypeScript compiler.
     */
    private compile;
    private convertExports;
    private convertReExports;
    /**
     * Resolve the project within the given context.
     *
     * @param context  The context object describing the current state the converter is in.
     * @returns The final project reflection.
     */
    private resolve;
    /**
     * Used to determine if we should immediately bail when creating a reflection.
     * Note: This should not be used for excludeNotDocumented because we don't have enough
     * information at this point since comment discovery hasn't happened.
     * @internal
     */
    shouldIgnore(symbol: ts.Symbol): boolean;
    private isExcluded;
    /** @internal */
    isExternal(symbol: ts.Symbol): boolean;
    processDocumentTags(reflection: Reflection, parent: ContainerReflection): void;
    private addDocument;
    private _buildCommentParserConfig;
}