typedoc
Version:
Create api documentation for TypeScript projects.
468 lines (467 loc) • 18.3 kB
TypeScript
import type { BundledTheme as ShikiTheme } from "@gerrit0/mini-shiki";
import type { LogLevel } from "../loggers.js";
import type { SortStrategy } from "../sort.js";
import type { EntryPointStrategy } from "../entry-point.js";
import type { ReflectionKind } from "../../models/reflections/kind.js";
import type { NeverIfInternal } from "../index.js";
import type { TranslationProxy } from "../../internationalization/internationalization.js";
/** @enum */
export declare const EmitStrategy: {
readonly both: "both";
readonly docs: "docs";
readonly none: "none";
};
/** @hidden */
export type EmitStrategy = (typeof EmitStrategy)[keyof typeof EmitStrategy];
/**
* Determines how TypeDoc searches for comments.
* @enum
*/
export declare const CommentStyle: {
readonly JSDoc: "jsdoc";
readonly Block: "block";
readonly Line: "line";
readonly All: "all";
};
export type CommentStyle = (typeof CommentStyle)[keyof typeof CommentStyle];
export type OutputSpecification = {
name: string;
path: string;
options?: Partial<TypeDocOptions>;
};
/**
* An interface describing all TypeDoc specific options. Generated from a
* map which contains more information about each option for better types when
* defining said options.
* @interface
*/
export type TypeDocOptions = {
[K in keyof TypeDocOptionMap]: unknown extends TypeDocOptionMap[K] ? unknown : TypeDocOptionMap[K] extends ManuallyValidatedOption<infer ManuallyValidated> ? ManuallyValidated : TypeDocOptionMap[K] extends string | string[] | number | boolean ? TypeDocOptionMap[K] : TypeDocOptionMap[K] extends Record<string, boolean> ? Partial<TypeDocOptionMap[K]> | boolean : keyof TypeDocOptionMap[K] | TypeDocOptionMap[K][keyof TypeDocOptionMap[K]];
};
/**
* Describes all TypeDoc specific options as returned by {@link Options.getValue}, this is
* slightly more restrictive than the {@link TypeDocOptions} since it does not allow both
* keys and values for mapped option types, and does not allow partials of flag values.
* @interface
*/
export type TypeDocOptionValues = {
[K in keyof TypeDocOptionMap]: unknown extends TypeDocOptionMap[K] ? unknown : TypeDocOptionMap[K] extends ManuallyValidatedOption<infer ManuallyValidated> ? ManuallyValidated : TypeDocOptionMap[K] extends string | string[] | number | boolean | Record<string, boolean> ? TypeDocOptionMap[K] : TypeDocOptionMap[K][keyof TypeDocOptionMap[K]];
};
/**
* Describes all TypeDoc options. Used internally to provide better types when fetching options.
* External consumers should likely use {@link TypeDocOptions} instead.
*
* If writing a plugin, you may find it useful to use declaration merging to add your options to this interface
* so that you have autocomplete when using `app.options.getValue`.
*
* ```ts
* declare module "typedoc" {
* export interface TypeDocOptionMap {
* pluginOption: string[];
* }
* }
* ```
*/
export interface TypeDocOptionMap {
options: string;
tsconfig: string;
compilerOptions: unknown;
plugin: string[];
lang: string;
locales: ManuallyValidatedOption<Record<string, Record<string, string>>>;
packageOptions: ManuallyValidatedOption<TypeDocOptions>;
entryPoints: string[];
entryPointStrategy: typeof EntryPointStrategy;
alwaysCreateEntryPointModule: boolean;
projectDocuments: string[];
exclude: string[];
externalPattern: string[];
excludeExternals: boolean;
excludeNotDocumented: boolean;
excludeNotDocumentedKinds: ReflectionKind.KindString[];
excludeInternal: boolean;
excludePrivate: boolean;
excludeProtected: boolean;
excludeReferences: boolean;
excludeCategories: string[];
maxTypeConversionDepth: number;
name: string;
includeVersion: boolean;
disableSources: boolean;
sourceLinkTemplate: string;
sourceLinkExternal: boolean;
markdownLinkExternal: boolean;
disableGit: boolean;
gitRevision: string;
gitRemote: string;
readme: string;
outputs: ManuallyValidatedOption<Array<OutputSpecification>>;
out: string;
html: string;
json: string;
pretty: boolean;
emit: typeof EmitStrategy;
theme: string;
lightHighlightTheme: ShikiTheme;
darkHighlightTheme: ShikiTheme;
highlightLanguages: string[];
ignoredHighlightLanguages: string[];
typePrintWidth: number;
customCss: string;
customJs: string;
markdownItOptions: ManuallyValidatedOption<Record<string, unknown>>;
/**
* Will be called when TypeDoc is setting up the markdown parser to use to render markdown.
* Can be used to add markdown-it plugins to the parser with code like this:
*
* ```ts
* // typedoc.config.mjs
* import iterator from "markdown-it-for-inline";
* export default {
* /** @param {MarkdownIt} parser *\/
* markdownItLoader(parser) {
* parser.use(iterator, "foo_replace", "text", function(tokens, idx) {
* tokens[idx].content = tokens[idx].content.replace(/foo/g, 'bar');
* });
* }
* }
* ```
*
* Note: Unfortunately, markdown-it doesn't ship its own types, so `parser` isn't
* strictly typed here.
*/
markdownItLoader: ManuallyValidatedOption<(parser: any) => void>;
basePath: string;
cname: string;
favicon: string;
githubPages: boolean;
hostedBaseUrl: string;
useHostedBaseUrlForAbsoluteLinks: boolean;
cacheBust: boolean;
hideGenerator: boolean;
customFooterHtml: string;
customFooterHtmlDisableWrapper: boolean;
searchInComments: boolean;
searchInDocuments: boolean;
cleanOutputDir: boolean;
titleLink: string;
navigationLinks: ManuallyValidatedOption<Record<string, string>>;
sidebarLinks: ManuallyValidatedOption<Record<string, string>>;
navigationLeaves: string[];
navigation: {
includeCategories: boolean;
includeGroups: boolean;
includeFolders: boolean;
compactFolders: boolean;
excludeReferences: boolean;
};
headings: {
readme: boolean;
document: boolean;
};
sluggerConfiguration: {
lowercase: boolean;
};
includeHierarchySummary: boolean;
visibilityFilters: ManuallyValidatedOption<{
protected?: boolean;
private?: boolean;
inherited?: boolean;
external?: boolean;
[tag: `@${string}`]: boolean;
}>;
searchCategoryBoosts: ManuallyValidatedOption<Record<string, number>>;
searchGroupBoosts: ManuallyValidatedOption<Record<string, number>>;
useFirstParagraphOfCommentAsSummary: boolean;
commentStyle: typeof CommentStyle;
useTsLinkResolution: boolean;
preserveLinkText: boolean;
jsDocCompatibility: JsDocCompatibility;
suppressCommentWarningsInDeclarationFiles: boolean;
blockTags: `@${string}`[];
inlineTags: `@${string}`[];
modifierTags: `@${string}`[];
excludeTags: `@${string}`[];
notRenderedTags: `@${string}`[];
externalSymbolLinkMappings: ManuallyValidatedOption<Record<string, Record<string, string>>>;
cascadedModifierTags: `@${string}`[];
categorizeByGroup: boolean;
groupReferencesByType: boolean;
defaultCategory: string;
categoryOrder: string[];
groupOrder: string[];
sort: SortStrategy[];
sortEntryPoints: boolean;
kindSortOrder: ReflectionKind.KindString[];
treatWarningsAsErrors: boolean;
treatValidationWarningsAsErrors: boolean;
intentionallyNotExported: string[];
validation: ValidationOptions;
requiredToBeDocumented: ReflectionKind.KindString[];
watch: boolean;
preserveWatchOutput: boolean;
help: boolean;
version: boolean;
showConfig: boolean;
logLevel: typeof LogLevel;
skipErrorChecking: boolean;
}
/**
* Wrapper type for values in TypeDocOptionMap which are represented with an unknown option type, but
* have a validation function that checks that they are the given type.
*/
export type ManuallyValidatedOption<T> = {
__validated: T;
};
export type ValidationOptions = {
/**
* If set, TypeDoc will produce warnings when a symbol is referenced by the documentation,
* but is not included in the documentation.
*/
notExported: boolean;
/**
* If set, TypeDoc will produce warnings about \{\@link\} tags which will produce broken links.
*/
invalidLink: boolean;
/**
* If set, TypeDoc will produce warnings about \{\@link\} tags which do not link directly to their target.
*/
rewrittenLink: boolean;
/**
* If set, TypeDoc will produce warnings about declarations that do not have doc comments
*/
notDocumented: boolean;
/**
* If set, TypeDoc will produce warnings about `@mergeModuleWith` tags which were not resolved.
*/
unusedMergeModuleWith: boolean;
};
export type JsDocCompatibility = {
/**
* If set, TypeDoc will treat `@example` blocks as code unless they contain a code block.
* On by default, this is how VSCode renders blocks.
*/
exampleTag: boolean;
/**
* If set, TypeDoc will treat `@default` blocks as code unless they contain a code block.
* On by default, this is how VSCode renders blocks.
*/
defaultTag: boolean;
/**
* If set, TypeDoc will warn if a `@inheritDoc` tag is spelled without TSDoc capitalization
* (i.e. `@inheritdoc`). On by default.
*/
inheritDocTag: boolean;
/**
* If set, TypeDoc will not emit warnings about unescaped `{` and `}` characters encountered
* when parsing a comment. On by default.
*/
ignoreUnescapedBraces: boolean;
};
/**
* Converts a given TypeDoc option key to the type of the declaration expected.
*/
export type KeyToDeclaration<K extends keyof TypeDocOptionMap> = TypeDocOptionMap[K] extends boolean ? BooleanDeclarationOption : TypeDocOptionMap[K] extends string ? StringDeclarationOption : TypeDocOptionMap[K] extends number ? NumberDeclarationOption : TypeDocOptionMap[K] extends string[] ? ArrayDeclarationOption : unknown extends TypeDocOptionMap[K] ? MixedDeclarationOption | ObjectDeclarationOption : TypeDocOptionMap[K] extends ManuallyValidatedOption<unknown> ? (MixedDeclarationOption & {
validate(value: unknown, i18n: TranslationProxy): void;
}) | (ObjectDeclarationOption & {
validate(value: unknown, i18n: TranslationProxy): void;
}) : TypeDocOptionMap[K] extends Record<string, boolean> ? FlagsDeclarationOption<TypeDocOptionMap[K]> : TypeDocOptionMap[K] extends Record<string | number, infer U> ? MapDeclarationOption<U> : never;
export declare enum ParameterHint {
File = 0,
Directory = 1
}
export declare enum ParameterType {
String = 0,
/**
* Resolved according to the config directory.
*/
Path = 1,
Number = 2,
Boolean = 3,
Map = 4,
Mixed = 5,
Array = 6,
/**
* Resolved according to the config directory.
*/
PathArray = 7,
/**
* Resolved according to the config directory if it starts with `.`
*/
ModuleArray = 8,
/**
* Resolved according to the config directory unless it starts with `**`, after skipping any leading `!` and `#` characters.
*/
GlobArray = 9,
/**
* An object which partially merges user-set values into the defaults.
*/
Object = 10,
/**
* An object with true/false flags
*/
Flags = 11
}
export interface DeclarationOptionBase {
/**
* The option name.
*/
name: string;
/**
* The help text to be displayed to the user when --help is passed.
*
* This may be a string, which will be presented directly, or a function,
* which will be called with an {@link TranslationProxy} so that option help
* can be translated into the user specified locale.
*/
help: NeverIfInternal<string> | ((i18n: TranslationProxy) => string);
/**
* The parameter type, used to convert user configuration values into the expected type.
* If not set, the type will be a string.
*/
type?: ParameterType;
/**
* If set, this option will be omitted from `--help`, and attempting to specify it on the command
* line will produce an error.
*/
configFileOnly?: boolean;
}
export interface StringDeclarationOption extends DeclarationOptionBase {
/**
* Specifies the resolution strategy. If `Path` is provided, values will be resolved according to their
* location in a file. If `String` or no value is provided, values will not be resolved.
*/
type?: ParameterType.String | ParameterType.Path;
/**
* If not specified defaults to the empty string for both `String` and `Path`.
*/
defaultValue?: string;
/**
* An optional hint for the type of input expected, will be displayed in the help output.
*/
hint?: ParameterHint;
/**
* If specified, when this output is specified TypeDoc will automatically add
* an output to the `outputs` option whose name is the value of this property with
* the path set to the value of this option. Should only be used with `type`
* set to {@link ParameterType.Path}.
*
* If any output shortcuts are set, the `outputs` option will be ignored.
*/
outputShortcut?: string;
/**
* An optional validation function that validates a potential value of this option.
* The function must throw an Error if the validation fails and should do nothing otherwise.
*/
validate?: (value: string, i18n: TranslationProxy) => void;
}
export interface NumberDeclarationOption extends DeclarationOptionBase {
type: ParameterType.Number;
/**
* Lowest possible value.
*/
minValue?: number;
/**
* Highest possible value.
*/
maxValue?: number;
/**
* If not specified defaults to 0.
*/
defaultValue?: number;
/**
* An optional validation function that validates a potential value of this option.
* The function must throw an Error if the validation fails and should do nothing otherwise.
*/
validate?: (value: number, i18n: TranslationProxy) => void;
}
export interface BooleanDeclarationOption extends DeclarationOptionBase {
type: ParameterType.Boolean;
/**
* If not specified defaults to false.
*/
defaultValue?: boolean;
}
export interface ArrayDeclarationOption extends DeclarationOptionBase {
type: ParameterType.Array | ParameterType.PathArray | ParameterType.ModuleArray | ParameterType.GlobArray;
/**
* If not specified defaults to an empty array.
*/
defaultValue?: readonly string[];
/**
* An optional validation function that validates a potential value of this option.
* The function must throw an Error if the validation fails and should do nothing otherwise.
*/
validate?: (value: string[], i18n: TranslationProxy) => void;
}
export interface MixedDeclarationOption extends DeclarationOptionBase {
type: ParameterType.Mixed;
/**
* If not specified defaults to undefined.
*/
defaultValue?: unknown;
/**
* An optional validation function that validates a potential value of this option.
* The function must throw an Error if the validation fails and should do nothing otherwise.
*/
validate?: (value: unknown, i18n: TranslationProxy) => void;
}
export interface ObjectDeclarationOption extends DeclarationOptionBase {
type: ParameterType.Object;
/**
* If not specified defaults to undefined.
*/
defaultValue?: unknown;
/**
* An optional validation function that validates a potential value of this option.
* The function must throw an Error if the validation fails and should do nothing otherwise.
*/
validate?: (value: unknown, i18n: TranslationProxy) => void;
}
export interface MapDeclarationOption<T> extends DeclarationOptionBase {
type: ParameterType.Map;
/**
* Maps a given value to the option type. The map type may be a TypeScript enum.
* In that case, when generating an error message for a mismatched key, the numeric
* keys will not be listed.
*/
map: Map<string, T> | Record<string | number, T>;
/**
* Unlike the rest of the option types, there is no sensible generic default for mapped option types.
* The default value for a mapped type must be specified.
*/
defaultValue: T;
}
export interface FlagsDeclarationOption<T extends Record<string, boolean>> extends DeclarationOptionBase {
type: ParameterType.Flags;
/**
* All of the possible flags, with their default values set.
*/
defaults: T;
}
export type DeclarationOption = StringDeclarationOption | NumberDeclarationOption | BooleanDeclarationOption | MixedDeclarationOption | ObjectDeclarationOption | MapDeclarationOption<unknown> | ArrayDeclarationOption | FlagsDeclarationOption<Record<string, boolean>>;
export interface ParameterTypeToOptionTypeMap {
[ParameterType.String]: string;
[ParameterType.Path]: string;
[ParameterType.Number]: number;
[ParameterType.Boolean]: boolean;
[ParameterType.Mixed]: unknown;
[ParameterType.Object]: unknown;
[ParameterType.Array]: string[];
[ParameterType.PathArray]: string[];
[ParameterType.ModuleArray]: string[];
[ParameterType.GlobArray]: string[];
[ParameterType.Flags]: Record<string, boolean>;
[ParameterType.Map]: unknown;
}
export type DeclarationOptionToOptionType<T extends DeclarationOption> = T extends MapDeclarationOption<infer U> ? U : T extends FlagsDeclarationOption<infer U> ? U : ParameterTypeToOptionTypeMap[Exclude<T["type"], undefined>];
/**
* The default conversion function used by the Options container. Readers may
* re-use this conversion function or implement their own. The arguments reader
* implements its own since 'false' should not be converted to true for a boolean option.
* @param value The value to convert.
* @param option The option for which the value should be converted.
* @returns The result of the conversion. Might be the value or an error.
*/
export declare function convert(value: unknown, option: DeclarationOption, i18n: TranslationProxy, configPath: string, oldValue?: unknown): unknown;
export declare function getDefaultValue(option: DeclarationOption): unknown;