typedoc

import type ts from "typescript"; import type { NeverIfInternal } from "../index.js"; import type { Application } from "../../../index.js"; import type { Logger } from "../loggers.js"; import { type DeclarationOption, type KeyToDeclaration, type TypeDocOptionMap, type TypeDocOptions, type TypeDocOptionValues } from "./declaration.js"; import type { TranslationProxy } from "../../internationalization/internationalization.js"; /** * Describes an option reader that discovers user configuration and converts it to the * TypeDoc format. */ export interface OptionsReader { /** * Readers will be processed according to their orders. * A higher order indicates that the reader should be called *later*. * * Note that to preserve expected behavior, the argv reader must have both the lowest * order so that it may set the location of config files used by other readers and * the highest order so that it can override settings from lower order readers. */ readonly order: number; /** * The name of this reader so that it may be removed by plugins without the plugin * accessing the instance performing the read. Multiple readers may have the same * name. */ readonly name: string; /** * Flag to indicate that this reader should be included in sub-options objects created * to read options for packages mode. */ readonly supportsPackages: boolean; /** * Read options from the reader's source and place them in the options parameter. * Options without a declared name may be treated as if they were declared with type * {@link ParameterType.Mixed}. Options which have been declared must be converted to the * correct type. As an alternative to doing this conversion in the reader, * the reader may use {@link Options.setValue}, which will correctly convert values. * @param container the options container that provides declarations * @param logger logger to be used to report errors * @param cwd the directory which should be treated as the current working directory for option file discovery */ read(container: Options, logger: Logger, cwd: string): void | Promise<void>; } /** * Maintains a collection of option declarations split into TypeDoc options * and TypeScript options. Ensures options are of the correct type for calling * code. * * ### Option Discovery * * Since plugins commonly add custom options, and TypeDoc does not permit options which have * not been declared to be set, options must be read twice. The first time options are read, * a noop logger is passed so that any errors are ignored. Then, after loading plugins, options * are read again, this time with the logger specified by the application. * * Options are read in a specific order. * 1. argv (0) - Must be read first since it should change the files read when * passing --options or --tsconfig. * 2. typedoc-json (100) - Read next so that it can specify the tsconfig.json file to read. * 3. tsconfig-json (200) - Last config file reader, cannot specify the typedoc.json file to read. * 4. argv (300) - Read argv again since any options set there should override those set in config * files. * * @group Common * @summary Contains all of TypeDoc's option declarations & values */ export declare class Options { private _readers; private _declarations; private _values; private _setOptions; private _compilerOptions; private _fileNames; private _projectReferences; private _i18n; /** * In packages mode, the directory of the package being converted. */ packageDir?: string; constructor(i18n: TranslationProxy); /** * Clones the options, intended for use in packages mode. */ copyForPackage(packageDir: string): Options; /** * Take a snapshot of option values now, used in tests only. * @internal */ snapshot(): { __optionSnapshot: never; }; /** * Take a snapshot of option values now, used in tests only. * @internal */ restore(snapshot: { __optionSnapshot: never; }): void; /** * Resets the option bag to all default values. * If a name is provided, will only reset that name. */ reset(name?: keyof TypeDocOptions): void; reset(name?: NeverIfInternal<string>): void; /** * Adds an option reader that will be used to read configuration values * from the command line, configuration files, or other locations. * @param reader */ addReader(reader: OptionsReader): void; read(logger: Logger, cwd?: string): Promise<void>; /** * Adds an option declaration to the container with extra type checking to ensure that * the runtime type is consistent with the declared type. * @param declaration The option declaration that should be added. */ addDeclaration<K extends keyof TypeDocOptions>(declaration: { name: K; } & KeyToDeclaration<K>): void; /** * Adds an option declaration to the container. * @param declaration The option declaration that should be added. */ addDeclaration(declaration: NeverIfInternal<Readonly<DeclarationOption>>): void; /** * Gets a declaration by one of its names. * @param name */ getDeclaration(name: string): Readonly<DeclarationOption> | undefined; /** * Gets all declared options. */ getDeclarations(): Readonly<DeclarationOption>[]; /** * Checks if the given option's value is deeply strict equal to the default. * @param name */ isSet(name: keyof TypeDocOptions): boolean; isSet(name: NeverIfInternal<string>): boolean; /** * Gets all of the TypeDoc option values defined in this option container. */ getRawValues(): Readonly<Partial<TypeDocOptions>>; /** * Gets a value for the given option key, throwing if the option has not been declared. * @param name */ getValue<K extends keyof TypeDocOptions>(name: K): TypeDocOptionValues[K]; getValue(name: NeverIfInternal<string>): unknown; /** * Sets the given declared option. Throws if setting the option fails. * @param name * @param value * @param configPath the directory to resolve Path type values against */ setValue<K extends keyof TypeDocOptions>(name: K, value: TypeDocOptions[K], configPath?: string): void; setValue(name: NeverIfInternal<string>, value: NeverIfInternal<unknown>, configPath?: NeverIfInternal<string>): void; /** * Gets the set compiler options. */ getCompilerOptions(): ts.CompilerOptions; /** @internal */ fixCompilerOptions(options: Readonly<ts.CompilerOptions>): ts.CompilerOptions; /** * Gets the file names discovered through reading a tsconfig file. */ getFileNames(): readonly string[]; /** * Gets the project references - used in solution style tsconfig setups. */ getProjectReferences(): readonly ts.ProjectReference[]; /** * Sets the compiler options that will be used to get a TS program. */ setCompilerOptions(fileNames: readonly string[], options: ts.CompilerOptions, projectReferences: readonly ts.ProjectReference[] | undefined): void; /** * Discover similar option names to the given name, for use in error reporting. */ getSimilarOptions(missingName: string): string[]; /** * Get the help message to be displayed to the user if `--help` is passed. */ getHelp(i18n: TranslationProxy): string; } /** * Binds an option to an accessor. Does not register the option. * * Note: This is a standard ES decorator. It will not work with pre-TS 5.0 experimental decorators enabled. */ export declare function Option<K extends keyof TypeDocOptionMap>(name: K): (_: unknown, _context: ClassAccessorDecoratorContext<{ application: Application; } | { options: Options; }, TypeDocOptionValues[K]>) => { get(this: { application: Application; } | { options: Options; }): TypeDocOptionValues[K]; set(_value: never): never; };