Typedoc

Application

TypeDoc のメインエントリーポイント。TypeScript ソースファイルのドキュメント変換を Converter と Renderer を通じてオーケストレーションする。

シグネチャ

class Application extends AbstractComponent<Application, ApplicationEvents> {
  // 静的メソッド
  static bootstrap(
    options?: Configuration.TypeDocOptions,
    readers?: readonly Configuration.OptionsReader[]
  ): Promise<Application>;

  static bootstrapWithPlugins(
    options?: Configuration.TypeDocOptions,
    readers?: readonly Configuration.OptionsReader[]
  ): Promise<Application>;

  // インスタンスメソッド
  convert(): Promise<Models.ProjectReflection | undefined>;
  convertAndWatch(
    success: (project: Models.ProjectReflection) => Promise<void>
  ): Promise<boolean>;
  generateDocs(project: Models.ProjectReflection, out: string): Promise<void>;
  generateJson(project: Models.ProjectReflection, out: string): Promise<void>;
  generateOutputs(project: Models.ProjectReflection): Promise<void>;
  validate(project: Models.ProjectReflection): void;
  getEntryPoints(): DocumentationEntryPoint[] | undefined;
  getDefinedEntryPoints(): DocumentationEntryPoint[] | undefined;
  getTypeScriptPath(): string;
  getTypeScriptVersion(): string;
  setOptions(options: Configuration.TypeDocOptions, reportErrors?: boolean): boolean;
  watchFile(path: string, shouldRestart?: boolean): void;
  toString(): string;

  // イベントメソッド
  on<K extends keyof ApplicationEvents>(
    event: K,
    listener: (this: undefined, ...args: ApplicationEvents[K]) => void,
    priority?: number
  ): void;
  off<K extends keyof ApplicationEvents>(
    event: K,
    listener: (this: undefined, ...args: ApplicationEvents[K]) => void
  ): void;
  trigger<K extends keyof ApplicationEvents>(
    event: K,
    ...args: ApplicationEvents[K]
  ): void;

  // プロパティ
  converter: Converter;
  renderer: Renderer;
  outputs: Outputs;
  serializer: Serializer;
  deserializer: Deserializer;
  options: Configuration.Options;
  logger: Logger;
  internationalization: Internationalization;
  /** @deprecated 0.29 で削除予定。ProjectReflection 上の参照を使用すること */
  files: Models.FileRegistry;
  componentName: string;

  // 静的プロパティ
  static readonly VERSION: string;

  // 静的イベント
  static readonly EVENT_BOOTSTRAP_END: string;
  static readonly EVENT_PROJECT_REVIVE: string;
  static readonly EVENT_VALIDATE_PROJECT: string;
  static readonly EVENT_GENERATE_OUTPUTS_BEGIN: string;
  static readonly EVENT_GENERATE_OUTPUTS_END: string;
}

主要メソッド

bootstrap()

static bootstrap(
  options?: Configuration.TypeDocOptions,
  readers?: readonly Configuration.OptionsReader[]
): Promise<Application>

プラグインをロードせずに TypeDoc を初期化する。テスト時やプラグインが不要な場合に使用する。

bootstrapWithPlugins()

static bootstrapWithPlugins(
  options?: Configuration.TypeDocOptions,
  readers?: readonly Configuration.OptionsReader[]
): Promise<Application>

プラグインのロードを有効にして TypeDoc を初期化する。通常のユースケースではこちらを使用する。

convert()

convert(): Promise<Models.ProjectReflection | undefined>

設定されたファイルに対してコンバーターを実行し、プロジェクト Reflection を返す。エラー時は undefined を返す。

convertAndWatch()

convertAndWatch(
  success: (project: Models.ProjectReflection) => Promise<void>
): Promise<boolean>

変換/ウォッチサイクルを実行し、各変換後にコールバックを実行する。再起動が必要な場合は true、エラー時は false を返す。

generateDocs()

generateDocs(project: Models.ProjectReflection, out: string): Promise<void>

プロジェクトの HTML ドキュメントを指定ディレクトリにレンダリングする。

generateJson()

generateJson(project: Models.ProjectReflection, out: string): Promise<void>

プロジェクト Reflection を JSON ファイルにシリアライズする。

generateOutputs()

generateOutputs(project: Models.ProjectReflection): Promise<void>

設定されたすべての出力形式を生成する。

validate()

validate(project: Models.ProjectReflection): void

プロジェクト Reflection に対してバリデーションを実行する。

getEntryPoints()

getEntryPoints(): DocumentationEntryPoint[] | undefined

ドキュメント化されたエントリーポイントを取得する。

getDefinedEntryPoints()

getDefinedEntryPoints(): DocumentationEntryPoint[] | undefined

ストラテジーオプションに従ってエントリーポイントを展開する。

setOptions()

setOptions(
  options: Configuration.TypeDocOptions,
  reportErrors?: boolean
): boolean

アプリケーションオプションを更新する。

getTypeScriptPath()

getTypeScriptPath(): string

TypeScript コンパイラへのパスを返す。

getTypeScriptVersion()

getTypeScriptVersion(): string

TypeScript バージョン文字列を返す。

watchFile()

watchFile(path: string, shouldRestart?: boolean): void

ウォッチモードでの再ビルド用にファイル依存関係を登録する。

主要プロパティ

converter

converter: Converter

宣言 Reflection を作成するコンバーターインスタンス。

renderer

renderer: Renderer

HTML 出力を生成するレンダラーインスタンス。

serializer

serializer: Serializer

JSON 出力を生成するシリアライザーインスタンス。

deserializer

deserializer: Deserializer

JSON から復元するデシリアライザーインスタンス。

options

options: Configuration.Options

設定コンテナ。オプションの取得・設定を行う。

logger

logger: Logger

メッセージ出力ユーティリティ。

internationalization

internationalization: Internationalization

翻訳サポート。addTranslations() で翻訳を追加できる。

outputs

outputs: Outputs

出力管理。

静的イベント

EVENT_BOOTSTRAP_END

プラグインのロードとオプションの凍結後に発火する。

EVENT_PROJECT_REVIVE

JSON デシリアライゼーション後に発火する。

EVENT_VALIDATE_PROJECT

バリデーション中に発火する。

EVENT_GENERATE_OUTPUTS_BEGIN

出力生成の直前に発火する。バリデーション警告があり treatWarningsAsErrors が有効な場合に補助ファイルの生成をスキップするプラグインで使用する。

EVENT_GENERATE_OUTPUTS_END

出力生成の直後に発火する。バリデーション警告があり treatWarningsAsErrors が有効な場合に補助ファイルの生成をスキップするプラグインで使用する。

アクセサ

コード例

import { Application } from "typedoc";

// プラグイン付きで初期化
const app = await Application.bootstrapWithPlugins({
  entryPoints: ["src/index.ts"],
  out: "docs",
});

// 変換
const project = await app.convert();

if (project) {
  // バリデーション
  app.validate(project);

  // HTML ドキュメント生成
  await app.generateDocs(project, "docs");

  // JSON 出力
  await app.generateJson(project, "docs/api.json");

  // すべての設定済み出力を生成
  await app.generateOutputs(project);
}

イベントリスニング

import { Application } from "typedoc";

const app = await Application.bootstrapWithPlugins();

// ブートストラップ完了後のイベント
app.on(Application.EVENT_BOOTSTRAP_END, () => {
  console.log("Bootstrap completed");
});

// バリデーションイベント
app.on(Application.EVENT_VALIDATE_PROJECT, (project) => {
  console.log(`Validating project: ${project.name}`);
});

関連

• Converter
• Renderer
• Options API
• Serialization
• アーキテクチャ概要

Converter

TypeScript ソースコードを Reflection モデルに変換するクラス。Application のサブコンポーネントとして動作する。

シグネチャ

class Converter extends AbstractComponent<Application, ConverterEvents> {
  // コア変換メソッド
  convert(entryPoints: readonly DocumentationEntryPoint[]): Models.ProjectReflection;
  convertSymbol(context: Context, symbol: ts.Symbol, exportSymbol?: ts.Symbol): void;
  convertType(context: Context, node: ts.TypeNode | undefined): Models.SomeType;
  convertType(context: Context, type: ts.Type, node?: ts.TypeNode): Models.SomeType;

  // ドキュメント管理
  addProjectDocuments(project: Models.ProjectReflection): void;
  parseRawComment(
    file: MinimalSourceFile,
    files: Models.FileRegistry
  ): { content: Models.CommentDisplayPart[]; frontmatter: Record<string, unknown> };
  processDocumentTags(reflection: Models.Reflection, parent: Models.ContainerReflection): void;

  // リンク解決
  resolveLinks(reflection: Models.Reflection): void;
  resolveLinks(comment: Models.Comment, owner: Models.Reflection): void;
  resolveLinks(
    parts: readonly Models.CommentDisplayPart[],
    owner: Models.Reflection
  ): Models.CommentDisplayPart[];
  resolveExternalLink(
    ref: DeclarationReference,
    refl: Models.Reflection,
    part: Models.CommentDisplayPart | undefined,
    symbolId: Models.ReflectionSymbolId | undefined
  ): string | ExternalResolveResult | undefined;

  // 外部シンボル解決
  addUnknownSymbolResolver(resolver: ExternalSymbolResolver): void;

  // 遅延変換
  permitDeferredConversion(): void;
  deferConversion(cb: () => void): void;
  finalizeDeferredConversion(): void;

  // フィルタリング
  shouldIgnore(symbol: ts.Symbol, checker: ts.TypeChecker): boolean;
  isExternal(symbol: ts.Symbol, checker: ts.TypeChecker): boolean;

  // イベントメソッド
  on<K extends keyof ConverterEvents>(
    event: K,
    listener: (this: undefined, ...args: ConverterEvents[K]) => void,
    priority?: number
  ): void;
  off<K extends keyof ConverterEvents>(
    event: K,
    listener: (this: undefined, ...args: ConverterEvents[K]) => void
  ): void;
  trigger<K extends keyof ConverterEvents>(
    event: K,
    ...args: ConverterEvents[K]
  ): void;

  // 静的イベント定数
  static readonly EVENT_BEGIN: "begin";
  static readonly EVENT_END: "end";
  static readonly EVENT_CREATE_PROJECT: "createProject";
  static readonly EVENT_CREATE_DECLARATION: "createDeclaration";
  static readonly EVENT_CREATE_DOCUMENT: "createDocument";
  static readonly EVENT_CREATE_SIGNATURE: "createSignature";
  static readonly EVENT_CREATE_PARAMETER: "createParameter";
  static readonly EVENT_CREATE_TYPE_PARAMETER: "createTypeParameter";
  static readonly EVENT_RESOLVE_BEGIN: "resolveBegin";
  static readonly EVENT_RESOLVE: "resolveReflection";
  static readonly EVENT_RESOLVE_END: "resolveEnd";

  // プロパティ
  componentName: string;
}

主要メソッド

convert()

convert(entryPoints: readonly DocumentationEntryPoint[]): Models.ProjectReflection

指定されたソースファイルをコンパイルし、プロジェクト Reflection を作成する。エントリーポイントの配列を受け取り、変換されたプロジェクトモデルを返す。

convertSymbol()

convertSymbol(context: Context, symbol: ts.Symbol, exportSymbol?: ts.Symbol): void

TypeScript シンボルを Reflection に変換する内部メソッド。

convertType()

convertType(context: Context, node: ts.TypeNode | undefined): Models.SomeType
convertType(context: Context, type: ts.Type, node?: ts.TypeNode): Models.SomeType

TypeScript の型を TypeDoc の型 Reflection に変換する。TypeNode または Type のいずれかを受け取るオーバーロードを持つ。

addProjectDocuments()

addProjectDocuments(project: Models.ProjectReflection): void

プロジェクトドキュメントを登録する内部メソッド。

parseRawComment()

parseRawComment(
  file: MinimalSourceFile,
  files: Models.FileRegistry
): { content: Models.CommentDisplayPart[]; frontmatter: Record<string, unknown> }

Markdown ファイルをコメントとフロントマターに解析する。

resolveLinks()

resolveLinks(reflection: Models.Reflection): void
resolveLinks(comment: Models.Comment, owner: Models.Reflection): void
resolveLinks(
  parts: readonly Models.CommentDisplayPart[],
  owner: Models.Reflection
): Models.CommentDisplayPart[]

Reflection やコメント内のドキュメントリンクを解決する。3つのオーバーロードがある。

addUnknownSymbolResolver()

addUnknownSymbolResolver(resolver: ExternalSymbolResolver): void

サードパーティライブラリのシンボルへのリンクを解決するリゾルバを追加する。テーマが外部シンボルのリンク先を決定するために使用される。

deferConversion() / permitDeferredConversion() / finalizeDeferredConversion()

permitDeferredConversion(): void      // v0.28.1+
deferConversion(cb: () => void): void // v0.28.0+
finalizeDeferredConversion(): void    // v0.28.1+

変換ステップを遅延実行するための API。

イベント定数

変換ライフサイクルイベント

作成イベント

解決イベント

アクセサ

コード例

基本的な変換

import { Application, Converter, Context, DeclarationReflection } from "typedoc";

export function load(app: Application) {
  // 変換開始時
  app.converter.on(Converter.EVENT_BEGIN, (context: Context) => {
    console.log("Conversion started");
  });

  // 宣言 Reflection 作成時
  app.converter.on(
    Converter.EVENT_CREATE_DECLARATION,
    (context: Context, reflection: DeclarationReflection) => {
      // Reflection のカスタマイズ
      if (reflection.name.startsWith("_")) {
        // 内部 API としてマーク
        reflection.setFlag(ReflectionFlag.Private, true);
      }
    }
  );

  // 解決処理完了時
  app.converter.on(Converter.EVENT_RESOLVE_END, (context: Context) => {
    const project = context.project;
    console.log(`Resolved ${Object.keys(project.reflections).length} reflections`);
  });
}

外部シンボルリゾルバ

import { Application } from "typedoc";

export function load(app: Application) {
  app.converter.addUnknownSymbolResolver((ref, refl, part, symbolId) => {
    if (ref.moduleSource === "react") {
      const name = ref.symbolReference?.path?.[0]?.path;
      if (name) {
        return `https://react.dev/reference/react/${name}`;
      }
    }
    return undefined;
  });
}

関連

• Application
• Reflections
• イベントシステム
• プラグイン開発

Events

TypeDoc のイベントシステム。Converter と Renderer のライフサイクル全体にわたるイベントディスパッチ機構。

シグネチャ

EventHooks

class EventHooks<T extends Record<keyof T, unknown[]>, R> {
  on<K extends keyof T>(
    event: K,
    listener: (...args: T[K]) => R,
    order?: number
  ): void;

  once<K extends keyof T>(
    event: K,
    listener: (...args: T[K]) => R,
    order?: number
  ): void;

  off<K extends keyof T>(
    event: K,
    listener: (...args: T[K]) => R
  ): void;

  emit<K extends keyof T>(
    event: K,
    ...args: T[K]
  ): R[];

  saveMomento(): EventHooksMomento<T, R>;
  restoreMomento(momento: EventHooksMomento<T, R>): void;
}

PageEvent

class PageEvent<Model extends RouterTarget = RouterTarget> {
  // 静的イベント
  static readonly BEGIN: "beginPage";
  static readonly END: "endPage";

  // プロパティ
  readonly model: Model;
  project: Models.ProjectReflection;
  filename: string;
  url: string;
  pageKind: PageKind;
  contents?: string;
  pageHeadings: PageHeading[];
  pageSections: { title: string; headings: PageHeading[] }[];

  // メソッド
  constructor(model: Model);
  isReflectionEvent(): this is PageEvent<Models.Reflection>;
  startNewSection(title: string): void;
}

RendererEvent

class RendererEvent {
  // 静的イベント
  static readonly BEGIN: "beginRender";
  static readonly END: "endRender";

  // プロパティ
  readonly outputDirectory: string;
  readonly project: Models.ProjectReflection;
  pages: PageDefinition<RouterTarget>[];

  constructor(
    outputDirectory: string,
    project: Models.ProjectReflection,
    pages: PageDefinition<RouterTarget>[]
  );
}

IndexEvent

class IndexEvent {
  // 静的イベント
  static readonly PREPARE_INDEX: "prepareIndex";

  // プロパティ
  searchResults: (Models.DeclarationReflection | Models.DocumentReflection)[];
  searchFields: Record<string, string>[];
  readonly searchFieldWeights: Record<string, number>;

  // メソッド
  constructor(
    searchResults: (Models.DeclarationReflection | Models.DocumentReflection)[]
  );
  removeResult(index: number): void;
}

MarkdownEvent

class MarkdownEvent {
  // 静的イベント
  static readonly PARSE: "parseMarkdown";

  // プロパティ
  readonly page: PageEvent;
  readonly originalText: string;
  parsedText: string;

  constructor(page: PageEvent, originalText: string, parsedText: string);
}

主要メソッド

EventHooks

on()

on<K extends keyof T>(
  event: K,
  listener: (...args: T[K]) => R,
  order?: number
): void

イベントリスナーを登録する。order で実行順序を制御できる（小さい値が先に実行）。

once()

once<K extends keyof T>(
  event: K,
  listener: (...args: T[K]) => R,
  order?: number
): void

1回だけ実行されるリスナーを登録する。

off()

off<K extends keyof T>(
  event: K,
  listener: (...args: T[K]) => R
): void

リスナーを解除する。

emit()

emit<K extends keyof T>(
  event: K,
  ...args: T[K]
): R[]

イベントを発火し、すべてのリスナーからの戻り値を収集する。

saveMomento() / restoreMomento()

saveMomento(): EventHooksMomento<T, R>
restoreMomento(momento: EventHooksMomento<T, R>): void

リスナーの状態を保存し、後で復元する。

PageEvent

isReflectionEvent()

isReflectionEvent(): this is PageEvent<Models.Reflection>

モデルが Reflection かどうかの型ガード。

startNewSection()

startNewSection(title: string): void

「On This Page」サイドバーに折りたたみ可能なセクションを作成する。

IndexEvent

removeResult()

removeResult(index: number): void

インデックスから検索結果を削除する。searchFields からも対応するエントリが同時に削除される。

主要プロパティ

PageEvent プロパティ

RendererEvent プロパティ

IndexEvent プロパティ

MarkdownEvent プロパティ

イベントライフサイクル

Converter ライフサイクル

EVENT_BEGIN
  → EVENT_CREATE_PROJECT
  → EVENT_CREATE_DECLARATION (各宣言ごと)
    → EVENT_CREATE_SIGNATURE (シグネチャごと)
    → EVENT_CREATE_PARAMETER (パラメータごと)
    → EVENT_CREATE_TYPE_PARAMETER (型パラメータごと)
  → EVENT_CREATE_DOCUMENT (ドキュメントごと)
  → EVENT_RESOLVE_BEGIN
  → EVENT_RESOLVE (各 Reflection ごと)
  → EVENT_RESOLVE_END
EVENT_END

Renderer ライフサイクル

preRenderAsyncJobs (非同期)
  → EVENT_BEGIN (RendererEvent)
    → EVENT_PREPARE_INDEX (IndexEvent)
    → EVENT_BEGIN_PAGE (PageEvent) ← 各ページ
    → EVENT_END_PAGE (PageEvent)   ← 各ページ
  → EVENT_END (RendererEvent)
postRenderAsyncJobs (非同期)

コード例

Converter イベントのリスニング

import { Application, Converter, Context, DeclarationReflection } from "typedoc";

export function load(app: Application) {
  // 変換開始
  app.converter.on(Converter.EVENT_BEGIN, (context: Context) => {
    app.logger.info("Conversion started");
  });

  // 宣言作成時
  app.converter.on(
    Converter.EVENT_CREATE_DECLARATION,
    (context: Context, reflection: DeclarationReflection) => {
      app.logger.info(`Created: ${reflection.name}`);
    }
  );

  // 解決処理完了時
  app.converter.on(Converter.EVENT_RESOLVE_END, (context: Context) => {
    app.logger.info(`Total reflections: ${
      Object.keys(context.project.reflections).length
    }`);
  });
}

Renderer イベントのリスニング

import { Application, Renderer, RendererEvent, PageEvent, Reflection } from "typedoc";

export function load(app: Application) {
  // レンダリング開始
  app.renderer.on(Renderer.EVENT_BEGIN, (event: RendererEvent) => {
    app.logger.info(`Output: ${event.outputDirectory}`);
  });

  // ページレンダリング後
  app.renderer.on(
    Renderer.EVENT_END_PAGE,
    (event: PageEvent<Reflection>) => {
      if (event.contents) {
        // HTML の修正
        event.contents += "<!-- Generated by MyPlugin -->";
      }
    }
  );
}

フックの使用

import { Application, JSX } from "typedoc";

export function load(app: Application) {
  // head にスタイルシートを追加
  app.renderer.hooks.on("head.end", () => (
    <link rel="stylesheet" href="custom.css" />
  ));

  // フッターにコンテンツを追加
  app.renderer.hooks.on("footer.end", () => (
    <div class="custom-footer">
      <p>Custom content</p>
    </div>
  ));
}

検索インデックスのカスタマイズ

import { Application, Renderer, IndexEvent } from "typedoc";

export function load(app: Application) {
  app.renderer.on(
    Renderer.EVENT_PREPARE_INDEX,
    (event: IndexEvent) => {
      // カスタム検索フィールドの追加
      for (let i = 0; i < event.searchResults.length; i++) {
        const refl = event.searchResults[i];
        event.searchFields[i]["category"] = refl.categories?.[0]?.title ?? "";
      }
      // フィールドの重みを設定
      (event.searchFieldWeights as any)["category"] = 5;
    }
  );
}

Markdown パース結果の修正

import { Application, MarkdownEvent } from "typedoc";

export function load(app: Application) {
  app.renderer.on(
    MarkdownEvent.PARSE,
    (event: MarkdownEvent) => {
      // パース済み HTML を修正
      event.parsedText = event.parsedText.replace(
        /TODO/g,
        '<span class="todo">TODO</span>'
      );
    }
  );
}

注意点

• イベントリスナーの this は undefined にバインドされる
• EventHooks はリスナーの戻り値を収集できる（Renderer フック向け）
• PageEvent.contents は EVENT_END_PAGE リスナーで変更可能
• IndexEvent.searchResults からアイテムを削除する場合は removeResult() を使用する
• searchFieldWeights は name が他のフィールドの 10 倍の重みを持つ
• order パラメータで実行順序を制御できる（小さい値が優先）
• saveMomento() / restoreMomento() でリスナーの状態を保存・復元できる

関連

• Converter
• Renderer
• Application
• プラグイン開発

Options

TypeDoc と TypeScript のオプション宣言を管理するクラス。型安全なオプションの取得・設定を提供する。

シグネチャ

class Options {
  constructor();

  // 宣言管理
  addDeclaration<K extends keyof TypeDocOptionMap>(
    declaration: { name: K } & KeyToDeclaration<K>
  ): void;
  getDeclaration(name: string): Readonly<DeclarationOption> | undefined;
  getDeclarations(): Readonly<DeclarationOption>[];

  // 値の操作
  getValue<K extends keyof TypeDocOptionMap>(name: K): TypeDocOptionValues[K];
  setValue<K extends keyof TypeDocOptionMap>(
    name: K,
    value: Exclude<TypeDocOptions[K], undefined>,
    configPath?: string
  ): void;
  isSet(name: keyof TypeDocOptionMap): boolean;
  getRawValues(): Readonly<Partial<TypeDocOptionValues>>;
  reset(name?: keyof TypeDocOptionMap): void;

  // リーダー管理
  addReader(reader: OptionsReader): void;
  read(logger: Logger, cwd?: string, usedFile?: (path: string) => void): Promise<void>;

  // コンパイラオプション
  getCompilerOptions(logger: Logger): ts.CompilerOptions;
  setCompilerOptions(
    fileNames: readonly string[],
    options: ts.CompilerOptions,
    projectReferences?: readonly ts.ProjectReference[]
  ): void;
  fixCompilerOptions(
    options: Readonly<ts.CompilerOptions>,
    logger: Logger
  ): ts.CompilerOptions;
  getFileNames(): readonly string[];
  getProjectReferences(): readonly ts.ProjectReference[];

  // ユーティリティ
  getHelp(): string;
  getSimilarOptions(missingName: string): string[];
  copyForPackage(packageDir: string): Options;
  snapshot(): { __optionSnapshot: never };
  restore(snapshot: { __optionSnapshot: never }): void;

  // プロパティ
  packageDir?: string;
}

主要メソッド

addDeclaration()

addDeclaration<K extends keyof TypeDocOptionMap>(
  declaration: { name: K } & KeyToDeclaration<K>
): void

新しいオプション宣言を追加する。プラグインでカスタムオプションを定義する際に使用する。

getValue()

getValue<K extends keyof TypeDocOptionMap>(name: K): TypeDocOptionValues[K]

指定されたオプションの現在の値を型安全に取得する。

setValue()

setValue<K extends keyof TypeDocOptionMap>(
  name: K,
  value: Exclude<TypeDocOptions[K], undefined>,
  configPath?: string
): void

指定されたオプションの値を設定する。configPath はファイルパスの解決に使用される。

isSet()

isSet(name: keyof TypeDocOptionMap): boolean

オプションが明示的に設定されているかどうかを返す（デフォルト値のままでないか）。

getRawValues()

getRawValues(): Readonly<Partial<TypeDocOptionValues>>

すべてのオプションの生の値を読み取り専用で返す。

reset()

reset(name?: keyof TypeDocOptionMap): void

指定されたオプション（または全オプション）をデフォルト値にリセットする。

addReader()

addReader(reader: OptionsReader): void

オプションリーダーを追加する。

read()

read(logger: Logger, cwd?: string, usedFile?: (path: string) => void): Promise<void>

登録されたすべてのリーダーからオプションを読み取る。

getCompilerOptions()

getCompilerOptions(logger: Logger): ts.CompilerOptions

TypeScript コンパイラオプションを取得する。

snapshot() / restore()

snapshot(): { __optionSnapshot: never }
restore(snapshot: { __optionSnapshot: never }): void

オプションの状態をスナップショットとして保存し、後で復元する。パッケージモードでの使用を想定。

主要プロパティ

packageDir

packageDir?: string

パッケージモードでのパッケージディレクトリ。

オプションリーダー

オプションは優先度順に読み取られる:

OptionsReader インターフェース

interface OptionsReader {
  name: string;
  readonly order: number;
  read(container: Options, logger: Logger, cwd: string): Promise<void> | void;
}

ParameterType 列挙型

enum ParameterType {
  String,         // 文字列値
  Path,           // ファイルパス (解決される)
  Number,         // 数値
  Boolean,        // 真偽値
  Map,            // キーと値のマップ
  Mixed,          // 混合型
  Array,          // 文字列配列
  PathArray,      // パス配列
  ModuleArray,    // モジュール配列
  GlobArray,      // Glob パターン配列
  Flags,          // フラグの組み合わせ
  Object,         // オブジェクト
}

コード例

カスタムオプションの定義

import { Application, ParameterType } from "typedoc";

export function load(app: Application) {
  // 文字列オプション
  app.options.addDeclaration({
    name: "myPluginTitle",
    help: "Title for the custom section",
    type: ParameterType.String,
    defaultValue: "Custom Section",
  });

  // ブールオプション
  app.options.addDeclaration({
    name: "myPluginEnabled",
    help: "Enable the custom plugin feature",
    type: ParameterType.Boolean,
    defaultValue: true,
  });

  // パスオプション
  app.options.addDeclaration({
    name: "myPluginOutput",
    help: "Output directory for custom files",
    type: ParameterType.Path,
    defaultValue: "./custom-output",
  });

  // マップオプション (列挙的な選択肢)
  app.options.addDeclaration({
    name: "myPluginFormat",
    help: "Output format",
    type: ParameterType.Map,
    map: new Map([
      ["json", "json"],
      ["yaml", "yaml"],
      ["xml", "xml"],
    ]),
    defaultValue: "json",
  });

  // 配列オプション
  app.options.addDeclaration({
    name: "myPluginExclude",
    help: "Patterns to exclude",
    type: ParameterType.GlobArray,
    defaultValue: [],
  });
}

オプション値の取得と使用

import { Application, Converter } from "typedoc";

export function load(app: Application) {
  app.converter.on(Converter.EVENT_RESOLVE_END, () => {
    // 型安全に値を取得
    const title = app.options.getValue("myPluginTitle");
    const enabled = app.options.getValue("myPluginEnabled");
    const output = app.options.getValue("myPluginOutput");

    if (enabled) {
      app.logger.info(`Plugin active with title: ${title}`);
      app.logger.info(`Output to: ${output}`);
    }

    // オプションが明示的に設定されているか確認
    if (app.options.isSet("myPluginTitle")) {
      app.logger.info("Title was explicitly configured");
    }
  });
}

オプションのスナップショット

// パッケージモードでの使用例
const snap = app.options.snapshot();
try {
  app.options.setValue("out", "./package-docs");
  // パッケージ固有の処理
} finally {
  app.options.restore(snap);
}

注意点

• オプションは Application.bootstrap() または bootstrapWithPlugins() 後に凍結される
• プラグインのカスタムオプションは load() 関数内で addDeclaration() を使用して宣言する
• ParameterType.Path はファイルパスを自動的に解決する
• リーダーの優先度により CLI 引数が最終的に他の設定を上書きする
• copyForPackage() はパッケージモードでパッケージごとのオプションコピーを作成する

関連

• Application
• プラグイン開発

API

Reflections

TypeDoc の内部モデル。ソースコード中のすべてのドキュメント対象要素（クラス、関数、プロパティなど）を表現する Reflection 階層。

シグネチャ

Reflection 階層

// 基底クラス
abstract class Reflection {
  abstract readonly variant: keyof ReflectionVariant;
  id: ReflectionId;
  name: string;
  kind: ReflectionKind;
  flags: ReflectionFlags;
  project: ProjectReflection;
  parent?: Reflection;
  comment?: Comment;
}

// コンテナ (子要素を持つ Reflection の基底)
abstract class ContainerReflection extends Reflection {
  children?: DeclarationReflection[];
  documents?: DocumentReflection[];
  childrenIncludingDocuments?: (DeclarationReflection | DocumentReflection)[];
  groups?: ReflectionGroup[];
  categories?: ReflectionCategory[];
}

// プロジェクト (ルート)
class ProjectReflection extends ContainerReflection {
  readonly variant: "project";
  files: FileRegistry;
  reflections: { [id: number]: Reflection };  // 読み取り専用
  packageName?: string;
  packageVersion?: string;
  readme?: CommentDisplayPart[];
}

// 宣言 (クラス、関数、プロパティなど)
class DeclarationReflection extends ContainerReflection {
  variant: "declaration" | "reference";
  type?: SomeType;
  typeParameters?: TypeParameterReflection[];
  signatures?: SignatureReflection[];
  indexSignatures?: SignatureReflection[];
  getSignature?: SignatureReflection;
  setSignature?: SignatureReflection;
  defaultValue?: string;
  extendedTypes?: SomeType[];
  extendedBy?: ReferenceType[];
  implementedTypes?: SomeType[];
  implementedBy?: ReferenceType[];
  inheritedFrom?: ReferenceType;
  overwrites?: ReferenceType;
  implementationOf?: ReferenceType;
  sources?: SourceReference[];
  packageVersion?: string;
  relevanceBoost?: number;
  typeHierarchy?: DeclarationHierarchy;
}

// シグネチャ
class SignatureReflection extends Reflection {
  readonly variant: "signature";
  parent: DeclarationReflection;
  parameters?: ParameterReflection[];
  typeParameters?: TypeParameterReflection[];
  type?: SomeType;
  overwrites?: ReferenceType;
  inheritedFrom?: ReferenceType;
  implementationOf?: ReferenceType;
  sources?: SourceReference[];
}

// パラメータ
class ParameterReflection extends Reflection {
  readonly variant: "param";
  parent?: SignatureReflection;
  type?: SomeType;
  defaultValue?: string;
}

// 型パラメータ
class TypeParameterReflection extends Reflection {
  readonly variant: "typeParam";
  parent?: DeclarationReflection | SignatureReflection;
  type?: SomeType;       // 制約
  default?: SomeType;    // デフォルト値
  varianceModifier?: VarianceModifier;
}

// リファレンス (インポートされた Reflection)
class ReferenceReflection extends DeclarationReflection {
  readonly variant: "reference";
  getTargetReflection(): Reflection;
  getTargetReflectionDeep(): Reflection;
  tryGetTargetReflection(): Reflection | undefined;
  tryGetTargetReflectionDeep(): Reflection | undefined;
}

// ドキュメント (Markdown ファイル)
class DocumentReflection extends Reflection {
  readonly variant: "document";
  content: CommentDisplayPart[];
  frontmatter: Record<string, unknown>;
  relevanceBoost?: number;
  children?: DocumentReflection[];
}

主要メソッド

Reflection (基底クラス)

型ガードメソッド

ProjectReflection

DeclarationReflection

ReferenceReflection

DocumentReflection

主要プロパティ

ReflectionKind (列挙型)

主な種類:

コード例

Reflection の走査

import {
  Application,
  Converter,
  Context,
  DeclarationReflection,
  ReflectionKind,
} from "typedoc";

export function load(app: Application) {
  app.converter.on(Converter.EVENT_RESOLVE_END, (context: Context) => {
    const project = context.project;

    // すべてのクラスを取得
    const classes = project.getReflectionsByKind(ReflectionKind.Class);
    for (const cls of classes) {
      if (cls.isDeclaration()) {
        console.log(`Class: ${cls.name}`);

        // メソッドを取得
        const methods = cls.getChildrenByKind(ReflectionKind.Method);
        for (const method of methods) {
          console.log(`  Method: ${method.name}`);
        }
      }
    }
  });
}

Reflection の修正

import { Application, Converter, DeclarationReflection } from "typedoc";

export function load(app: Application) {
  app.converter.on(
    Converter.EVENT_CREATE_DECLARATION,
    (_context: Context, reflection: DeclarationReflection) => {
      // コメントの追加
      if (!reflection.comment) {
        reflection.comment = new Comment();
      }

      // Reflection の削除
      if (reflection.name.startsWith("__internal")) {
        const project = reflection.project;
        project.removeReflection(reflection);
      }
    }
  );
}

ビジターパターン

import { ReflectionVisitor } from "typedoc";

const visitor: ReflectionVisitor = {
  declaration(reflection) {
    console.log(`Declaration: ${reflection.name}`);
  },
  signature(reflection) {
    console.log(`Signature: ${reflection.name}`);
  },
  parameter(reflection) {
    console.log(`Parameter: ${reflection.name}`);
  },
};

project.visit(visitor);

関連

• Types
• Converter
• Serialization
• アーキテクチャ概要

Renderer

ProjectReflection を Theme インスタンスで処理し、HTML ドキュメントを出力ディレクトリに書き込むクラス。

シグネチャ

class Renderer extends AbstractComponent<Application, RendererEvents> {
  // メソッド
  render(project: Models.ProjectReflection, outputDirectory: string): Promise<void>;
  defineTheme(name: string, theme: new (renderer: Renderer) => Theme): void;
  defineRouter(name: string, router: new (app: Application) => Router): void;
  removeTheme(name: string): void;
  removeRouter(name: string): void;

  // イベントメソッド
  on<K extends keyof RendererEvents>(
    event: K,
    listener: (this: undefined, ...args: RendererEvents[K]) => void,
    priority?: number
  ): void;
  off<K extends keyof RendererEvents>(
    event: K,
    listener: (this: undefined, ...args: RendererEvents[K]) => void
  ): void;
  trigger<K extends keyof RendererEvents>(
    event: K,
    ...args: RendererEvents[K]
  ): void;

  // プロパティ
  theme?: Theme;
  router?: Router;
  hooks: EventHooks<RendererHooks, JSX.Element>;
  preRenderAsyncJobs: ((output: RendererEvent) => Promise<void>)[];
  postRenderAsyncJobs: ((output: RendererEvent) => Promise<void>)[];
  renderStartTime: number;
  markedPlugin: MarkedPlugin;
  cacheBust: boolean;
  componentName: string;

  // 静的イベント定数
  static readonly EVENT_BEGIN: "beginRender";
  static readonly EVENT_END: "endRender";
  static readonly EVENT_BEGIN_PAGE: "beginPage";
  static readonly EVENT_END_PAGE: "endPage";
  static readonly EVENT_PREPARE_INDEX: "prepareIndex";
}

主要メソッド

render()

render(project: Models.ProjectReflection, outputDirectory: string): Promise<void>

プロジェクト Reflection を処理し、HTML ドキュメントを指定ディレクトリに出力する。以下の順序で処理が行われる:

1. preRenderAsyncJobs を実行 2. EVENT_BEGIN イベントを発火 3. 各ページの EVENT_BEGIN_PAGE → レンダリング → EVENT_END_PAGE を実行 4. EVENT_END イベントを発火 5. postRenderAsyncJobs を実行

defineTheme()

defineTheme(name: string, theme: new (renderer: Renderer) => Theme): void

カスタムテーマを登録する。テーマ名と Theme を継承するクラスのコンストラクタを受け取る。

defineRouter()

defineRouter(name: string, router: new (app: Application) => Router): void

カスタムルーターを登録する。URL 構造をカスタマイズする際に使用する。

removeTheme()

removeTheme(name: string): void

登録済みテーマを削除する。

removeRouter()

removeRouter(name: string): void

登録済みルーターを削除する。

主要プロパティ

theme

theme?: Theme

現在アクティブなテーマインスタンス。レンダリング開始時に設定される。

router

router?: Router

現在アクティブなルーターインスタンス。URL 生成に使用される。

hooks

hooks: EventHooks<RendererHooks, JSX.Element>

プラグインが HTML にコンテンツを注入するためのフックシステム。テーマ全体を書き換えずに部分的なカスタマイズが可能。

利用可能なフック: head.end, body.begin, body.end, content.begin, content.end, sidebar.begin, sidebar.end, pageSidebar.begin, pageSidebar.end, footer.begin, footer.end

preRenderAsyncJobs

preRenderAsyncJobs: ((output: RendererEvent) => Promise<void>)[]

ドキュメント生成前に実行される非同期コールバックの配列。

postRenderAsyncJobs

postRenderAsyncJobs: ((output: RendererEvent) => Promise<void>)[]

ドキュメント書き込み後に実行される非同期コールバックの配列。

renderStartTime

renderStartTime: number

レンダリング開始時のタイムスタンプ。

markedPlugin

markedPlugin: MarkedPlugin

Markdown パーシングプラグイン。

イベント定数

アクセサ

コード例

テーマの定義

import { Application, DefaultTheme, Renderer } from "typedoc";

class MyTheme extends DefaultTheme {
  // カスタムテーマの実装
}

export function load(app: Application) {
  app.renderer.defineTheme("my-theme", MyTheme);
}

フックの使用

import { Application, JSX } from "typedoc";

export function load(app: Application) {
  // head にカスタム CSS を追加
  app.renderer.hooks.on("head.end", () => (
    <link rel="stylesheet" href="custom.css" />
  ));

  // フッターにバージョン情報を追加
  app.renderer.hooks.on("footer.end", () => (
    <p>Generated with MyPlugin v1.0</p>
  ));
}

レンダリングイベントのリスニング

import { Application, Renderer, PageEvent, RendererEvent, Reflection } from "typedoc";

export function load(app: Application) {
  // レンダリング開始時
  app.renderer.on(Renderer.EVENT_BEGIN, (event: RendererEvent) => {
    console.log(`Rendering to: ${event.outputDirectory}`);
    console.log(`Pages to generate: ${event.pages.length}`);
  });

  // 各ページのレンダリング後
  app.renderer.on(Renderer.EVENT_END_PAGE, (event: PageEvent<Reflection>) => {
    if (event.contents) {
      // HTML コンテンツの修正
      event.contents = event.contents.replace("old-text", "new-text");
    }
  });

  // 非同期ジョブ
  app.renderer.preRenderAsyncJobs.push(async (output) => {
    // レンダリング前の準備処理
  });

  app.renderer.postRenderAsyncJobs.push(async (output) => {
    // レンダリング後のクリーンアップ処理
  });
}

関連

• Application
• イベントシステム
• カスタムテーマ
• プラグイン開発

Serialization

TypeDoc のシリアライゼーションシステム。Reflection モデルと JSON 間の変換を行う Serializer と Deserializer クラス。

シグネチャ

Serializer

class Serializer extends EventDispatcher<SerializerEvents> {
  // 静的イベント
  static readonly EVENT_BEGIN: "begin";
  static readonly EVENT_END: "end";

  // プロパティ
  projectRoot: NormalizedPath;
  project: Models.ProjectReflection;

  // コアメソッド
  projectToObject(
    value: Models.ProjectReflection,
    projectRoot: NormalizedPath
  ): JSONOutput.ProjectReflection;

  toObject<T extends { toObject(serializer: Serializer): ModelToObject<T> }>(
    value: T | undefined
  ): ModelToObject<T> | undefined;

  toObjectsOptional<T extends { toObject(serializer: Serializer): ModelToObject<T> }>(
    value: T[] | undefined
  ): ModelToObject<T>[] | undefined;

  // コンポーネント管理
  addSerializer<T extends object>(serializer: SerializerComponent<T>): void;
  removeSerializer(serializer: SerializerComponent<any>): void;

  // イベントメソッド
  on<K extends keyof SerializerEvents>(
    event: K,
    listener: (...args: SerializerEvents[K]) => void,
    priority?: number
  ): void;
  off<K extends keyof SerializerEvents>(
    event: K,
    listener: (...args: SerializerEvents[K]) => void
  ): void;
  trigger<K extends keyof SerializerEvents>(
    event: K,
    ...args: SerializerEvents[K]
  ): void;
}

Deserializer

class Deserializer {
  // プロパティ
  logger: Logger;
  projectRoot: NormalizedPath;
  oldIdToNewId: Record<ReflectionId, ReflectionId | undefined>;
  oldFileIdToNewFileId: Record<FileId, FileId | undefined>;
  project: ProjectReflection | undefined;
  reflectionBuilders: Record<string, Function>;
  typeBuilders: Record<string, Function>;

  // コアメソッド
  constructor(logger: Logger);

  reviveProject(
    name: string,
    projectObj: JSONOutput.ProjectReflection,
    options: { projectRoot: NormalizedPath; registry: FileRegistry }
  ): ProjectReflection;

  reviveProjects(
    name: string,
    projects: readonly JSONOutput.ProjectReflection[],
    options: {
      projectRoot: NormalizedPath;
      registry: FileRegistry;
      alwaysCreateEntryPointModule: boolean;
    }
  ): ProjectReflection;

  revive<T>(obj: T | undefined): T | undefined;
  reviveMany<T>(arr: T[] | undefined): T[] | undefined;

  constructReflection<T>(obj: JSONOutput.Reflection): T;
  constructType(obj: JSONOutput.SomeType): Models.SomeType;
  reviveType(obj: JSONOutput.SomeType | undefined): Models.SomeType | undefined;

  fromObject<T>(receiver: T, obj: unknown): void;

  addDeserializer(deserializer: DeserializerComponent): void;
  defer(cb: (project: ProjectReflection) => void): void;
}

主要メソッド

Serializer

projectToObject()

projectToObject(
  value: Models.ProjectReflection,
  projectRoot: NormalizedPath
): JSONOutput.ProjectReflection

プロジェクト Reflection 全体を JSON オブジェクトに変換する。begin/end イベントを発火する。

toObject()

toObject<T>(value: T | undefined): ModelToObject<T> | undefined

個々のモデルオブジェクトを JSON 表現に変換する。各モデルの toObject() メソッドを呼び出す。

toObjectsOptional()

toObjectsOptional<T>(value: T[] | undefined): ModelToObject<T>[] | undefined

オプションのモデル配列をシリアライズする。

addSerializer()

addSerializer<T extends object>(serializer: SerializerComponent<T>): void

カスタムシリアライザーコンポーネントを追加する。

removeSerializer()

removeSerializer(serializer: SerializerComponent<any>): void

シリアライザーコンポーネントを削除する。

Deserializer

reviveProject()

reviveProject(
  name: string,
  projectObj: JSONOutput.ProjectReflection,
  options: { projectRoot: NormalizedPath; registry: FileRegistry }
): ProjectReflection

単一の JSON プロジェクトを ProjectReflection に復元する。

reviveProjects()

reviveProjects(
  name: string,
  projects: readonly JSONOutput.ProjectReflection[],
  options: {
    projectRoot: NormalizedPath;
    registry: FileRegistry;
    alwaysCreateEntryPointModule: boolean;
  }
): ProjectReflection

複数の JSON プロジェクトを処理し、統合された ProjectReflection を返す。

constructReflection()

constructReflection<T>(obj: JSONOutput.Reflection): T

JSON から Reflection インスタンスを構築する。variant フィールドに基づいて適切なクラスを選択する。

constructType()

constructType(obj: JSONOutput.SomeType): Models.SomeType

JSON から Type インスタンスを構築する。type フィールドに基づいて適切なクラスを選択する。

defer()

defer(cb: (project: ProjectReflection) => void): void

デシリアライゼーション完了後に実行されるコールバックを遅延登録する。相互参照の解決に使用する。

主要プロパティ

Serializer プロパティ

Deserializer プロパティ

イベント

Serializer イベント

JSONOutput 名前空間

シリアライズされた JSON の型定義。外部ツールで TypeDoc の JSON 出力を消費する際に使用する。

主要インターフェース

namespace JSONOutput {
  interface ProjectReflection {
    id: number;
    name: string;
    variant: "project";
    kind: number;
    children?: DeclarationReflection[];
    groups?: ReflectionGroup[];
    categories?: ReflectionCategory[];
    packageName?: string;
    packageVersion?: string;
    readme?: CommentDisplayPart[];
    // ...
  }

  interface DeclarationReflection {
    id: number;
    name: string;
    variant: "declaration";
    kind: number;
    type?: SomeType;
    signatures?: SignatureReflection[];
    children?: DeclarationReflection[];
    // ...
  }

  interface SignatureReflection {
    id: number;
    name: string;
    variant: "signature";
    kind: number;
    parameters?: ParameterReflection[];
    typeParameters?: TypeParameterReflection[];
    type?: SomeType;
    // ...
  }

  // SomeType は各型の JSON 表現のユニオン
  type SomeType =
    | ArrayType
    | ConditionalType
    | IndexedAccessType
    | InferredType
    | IntersectionType
    | IntrinsicType
    | LiteralType
    | MappedType
    | OptionalType
    | PredicateType
    | QueryType
    | ReferenceType
    | RestType
    | TemplateLiteralType
    | TupleType
    | TypeOperatorType
    | UnionType
    | UnknownType;
}

コード例

JSON への出力

import { Application } from "typedoc";

const app = await Application.bootstrapWithPlugins({
  entryPoints: ["src/index.ts"],
});

const project = await app.convert();
if (project) {
  // JSON ファイルへの出力
  await app.generateJson(project, "./api.json");

  // プログラムから JSON オブジェクトを取得
  const jsonObj = app.serializer.projectToObject(project, "/path/to/project");
}

JSON からの復元

import { Application, Models } from "typedoc";
import * as fs from "fs";

const app = await Application.bootstrapWithPlugins();

const jsonData = JSON.parse(fs.readFileSync("./api.json", "utf-8"));
const project = app.deserializer.reviveProject(
  "MyProject",
  jsonData,
  {
    projectRoot: "/path/to/project" as any,
    registry: new Models.FileRegistry(),
  }
);

// 復元された ProjectReflection を使用
await app.generateDocs(project, "./docs");

カスタムシリアライザー

import { Application, Serializer, DeclarationReflection } from "typedoc";

export function load(app: Application) {
  // シリアライゼーション開始時のリスナー
  app.serializer.on(Serializer.EVENT_BEGIN, () => {
    app.logger.info("Serialization started");
  });

  // シリアライゼーション完了時のリスナー
  app.serializer.on(Serializer.EVENT_END, () => {
    app.logger.info("Serialization completed");
  });
}

JSON 出力の後処理

import { Application } from "typedoc";
import * as fs from "fs";

const app = await Application.bootstrapWithPlugins({
  entryPoints: ["src/index.ts"],
});

const project = await app.convert();
if (project) {
  const json = app.serializer.projectToObject(project, "/path/to/project");

  // JSON を加工
  const enhanced = {
    ...json,
    generatedAt: new Date().toISOString(),
    generatorVersion: Application.VERSION,
  };

  fs.writeFileSync("./api-enhanced.json", JSON.stringify(enhanced, null, 2));
}

注意点

• Serializer は EventDispatcher を継承し、begin/end イベントを発火する
• Deserializer はイベントを発火しない
• JSONOutput 名前空間の型は外部ツールで JSON を消費する際に有用
• Deserializer.defer() はデシリアライゼーション完了後に実行されるため、相互参照の解決に適している
• oldIdToNewId マッピングは複数プロジェクトを統合する際の ID 衝突を解決する
• JSON 出力の形式は TypeDoc のバージョン間で変更される可能性がある

関連

• Application
• Reflections
• Types
• アーキテクチャ概要

Types

TypeDoc の型システム。TypeScript の型を表現する 18 の Type サブクラス。

シグネチャ

基底クラス: Type

abstract class Type {
  abstract readonly type: string;

  // 共通メソッド
  toString(): string;
  stringify(context: TypeContext): string;
  visit<T, A extends unknown[]>(visitor: TypeVisitor<T, A>, ...args: A): T;
  estimatePrintWidth(): number;
  toObject(serializer: Serializer): JSONOutput.SomeType;
  fromObject(deserializer: Deserializer, obj: JSONOutput.SomeType): void;

  // 保護メソッド
  protected abstract getTypeString(): string;
  abstract needsParenthesis(context: TypeContext): boolean;
}

主要メソッド

Type (基底クラス) 共通メソッド

全 18 サブクラス

ArrayType

配列型を表現する (string[])。

class ArrayType extends Type {
  readonly type: "array";
  elementType: SomeType;

  constructor(elementType: SomeType);
}

---

ConditionalType

条件型を表現する (T extends U ? X : Y)。

class ConditionalType extends Type {
  readonly type: "conditional";
  checkType: SomeType;
  extendsType: SomeType;
  trueType: SomeType;
  falseType: SomeType;

  constructor(
    checkType: SomeType,
    extendsType: SomeType,
    trueType: SomeType,
    falseType: SomeType
  );
}

---

IndexedAccessType

インデックスアクセス型を表現する (T[K])。

class IndexedAccessType extends Type {
  readonly type: "indexedAccess";
  objectType: SomeType;
  indexType: SomeType;

  constructor(objectType: SomeType, indexType: SomeType);
}

---

InferredType

推論型を表現する (infer T)。

class InferredType extends Type {
  readonly type: "inferred";
  name: string;
  constraint?: SomeType;

  constructor(name: string, constraint?: SomeType);
}

---

IntersectionType

交差型を表現する (A & B)。

class IntersectionType extends Type {
  readonly type: "intersection";
  types: SomeType[];

  constructor(types: SomeType[]);
}

---

IntrinsicType

組み込み型を表現する (string, number, boolean など)。

class IntrinsicType extends Type {
  readonly type: "intrinsic";
  name: string;

  constructor(name: string);
}

---

LiteralType

リテラル型を表現する ("hello", 42, true など)。

class LiteralType extends Type {
  readonly type: "literal";
  value: string | number | bigint | boolean | null;

  constructor(value: string | number | bigint | boolean | null);
}

---

MappedType

マップ型を表現する ({ [K in T]: U })。

class MappedType extends Type {
  readonly type: "mapped";
  parameter: string;
  parameterType: SomeType;
  templateType: SomeType;
  readonlyModifier?: "+" | "-";
  optionalModifier?: "+" | "-";
  nameType?: SomeType;

  constructor(
    parameter: string,
    parameterType: SomeType,
    templateType: SomeType,
    readonlyModifier?: "+" | "-",
    optionalModifier?: "+" | "-",
    nameType?: SomeType
  );
}

---

OptionalType

オプション型を表現する (タプル内の T?)。

class OptionalType extends Type {
  readonly type: "optional";
  elementType: SomeType;

  constructor(elementType: SomeType);
}

---

PredicateType

型述語を表現する (x is string)。

class PredicateType extends Type {
  readonly type: "predicate";
  name: string;
  asserts: boolean;
  targetType?: SomeType;

  constructor(name: string, asserts: boolean, targetType?: SomeType);
}

---

QueryType

型クエリを表現する (typeof X)。

class QueryType extends Type {
  readonly type: "query";
  queryType: ReferenceType;

  constructor(queryType: ReferenceType);
}

---

ReferenceType

他の Reflection を参照する型を表現する (クラス、インターフェース、列挙型など)。

class ReferenceType extends Type {
  readonly type: "reference";
  name: string;
  typeArguments?: SomeType[];
  highlightedProperties?: Map<string, CommentDisplayPart[]>;
  qualifiedName: string;
  externalUrl?: string;
  package?: string;
  refersToTypeParameter: boolean;
  preferValues: boolean;

  // アクセサ
  get reflection(): Reflection | undefined;
  get symbolId(): ReflectionSymbolId | undefined;

  // 静的ファクトリメソッド
  static createResolvedReference(
    name: string,
    target: Reflection | ReflectionId,
    project: ProjectReflection
  ): ReferenceType;

  static createUnresolvedReference(
    name: string,
    target: ReflectionSymbolId,
    project: ProjectReflection,
    qualifiedName: string
  ): ReferenceType;

  static createBrokenReference(
    name: string,
    project: ProjectReflection,
    packageName?: string
  ): ReferenceType;

  // メソッド
  toDeclarationReference(): DeclarationReference;
  isIntentionallyBroken(): boolean;
}

---

RestType

残余型を表現する (...T)。

class RestType extends Type {
  readonly type: "rest";
  elementType: SomeType;

  constructor(elementType: SomeType);
}

---

TemplateLiteralType

テンプレートリテラル型を表現する (` hello${string} `)。

class TemplateLiteralType extends Type {
  readonly type: "templateLiteral";
  head: string;
  tail: [SomeType, string][];

  constructor(head: string, tail: [SomeType, string][]);
}

---

TupleType

タプル型を表現する ([string, number])。

class TupleType extends Type {
  readonly type: "tuple";
  elements: SomeType[];

  constructor(elements: SomeType[]);
}

---

TypeOperatorType

型演算子を表現する (keyof T, unique T, readonly T)。

class TypeOperatorType extends Type {
  readonly type: "typeOperator";
  operator: "keyof" | "unique" | "readonly";
  target: SomeType;

  constructor(operator: "keyof" | "unique" | "readonly", target: SomeType);
}

---

UnionType

共用体型を表現する (A | B)。

class UnionType extends Type {
  readonly type: "union";
  types: SomeType[];
  elementSummaries?: CommentDisplayPart[][];

  constructor(types: SomeType[]);
}

---

UnknownType

未知の型を表現する。TypeDoc が認識できない型の場合に使用される。

class UnknownType extends Type {
  readonly type: "unknown";
  name: string;

  constructor(name: string);
}

コード例

ビジターパターンによる型処理

import { Models } from "typedoc";

function processType(type: Models.SomeType): string {
  return type.visit({
    array(t) {
      return `Array of ${processType(t.elementType)}`;
    },
    union(t) {
      return t.types.map(processType).join(" | ");
    },
    intersection(t) {
      return t.types.map(processType).join(" & ");
    },
    reference(t) {
      const args = t.typeArguments
        ? `<${t.typeArguments.map(processType).join(", ")}>`
        : "";
      return `${t.name}${args}`;
    },
    intrinsic(t) {
      return t.name;
    },
    literal(t) {
      return String(t.value);
    },
    // 他の型はデフォルトで toString() を使用
  });
}

型の判別

import { Models } from "typedoc";

function analyzeType(type: Models.SomeType): void {
  switch (type.type) {
    case "reference":
      console.log(`Reference to: ${type.name}`);
      if (type.reflection) {
        console.log(`  Resolved to: ${type.reflection.getFullName()}`);
      }
      break;
    case "union":
      console.log(`Union of ${type.types.length} types`);
      break;
    case "array":
      console.log(`Array of ${type.elementType}`);
      break;
    case "intrinsic":
      console.log(`Built-in: ${type.name}`);
      break;
    // ...
  }
}

関連

• Reflections
• Converter
• Serialization

TypeDoc カスタムテーマ

TypeDoc のテーマシステムを拡張し、カスタム HTML 出力を作成する方法。

詳細説明

テーマの定義

テーマはプラグインから Application.renderer.defineTheme() を呼び出して定義する。最も基本的な実装は DefaultTheme を継承する方法:

import { Application, DefaultTheme } from "typedoc";

export function load(app: Application) {
  app.renderer.defineTheme("mydefault", DefaultTheme);
}

DefaultTheme の拡張

カスタムテーマは DefaultTheme を継承し、getRenderContext() をオーバーライドしてカスタムコンテキストを返す:

import {
  Application,
  DefaultTheme,
  DefaultThemeRenderContext,
  PageEvent,
  Reflection,
  Options,
  JSX,
} from "typedoc";

class MyThemeContext extends DefaultThemeRenderContext {
  // テンプレートメソッドをオーバーライド
  override footer = (context: DefaultThemeRenderContext) => {
    return (
      <footer>
        {context.hook("footer.begin", context)}
        Copyright 2024
        {context.hook("footer.end", context)}
      </footer>
    );
  };
}

class MyTheme extends DefaultTheme {
  getRenderContext(pageEvent: PageEvent<Reflection>): MyThemeContext {
    return new MyThemeContext(this, pageEvent, this.application.options);
  }
}

export function load(app: Application) {
  app.renderer.defineTheme("mytheme", MyTheme);
}

DefaultThemeRenderContext

DefaultThemeRenderContext はテーマのすべてのテンプレートメソッドを提供するクラス。コンストラクタは以下の引数を取る:

constructor(theme: DefaultTheme, page: PageEvent<Reflection>, options: Options)

主要テンプレートメソッド

重要: this を使用するテンプレート関数は必ずバインドする必要がある。アロー関数を使用するか、コンストラクタで this.myMethod = this.myMethod.bind(this) を呼ぶこと。

フックシステム

フックを使うと、テーマ全体を書き換えることなく HTML にコンテンツを注入できる。

利用可能なフック

フックは RendererHooks インターフェースで詳細が定義されている。

リフレクションアイコン（v0.28 以降）

DefaultThemeRenderContext.reflectionIcon を使用すると、リフレクションの種類ごとのアイコン表示をきめ細かく制御できる。アイコン全体を差し替えるのではなく、特定の種類のみ変更可能。

CSS レイヤー（v0.28 以降）

デフォルトテーマの CSS は @layer typedoc でラップされる。カスタム CSS でスタイルを上書きする際に @layer を活用することで、カスケードの優先順位を制御しやすくなる。

非同期ジョブ

レンダリング前後に非同期処理を実行するためのキュー:

• `preRenderAsyncJobs`: ドキュメント生成前に実行
• `postRenderAsyncJobs`: ドキュメント書き込み後に実行

カスタム JSX 要素

TypeDoc の IntrinsicElements インターフェースを拡張して独自の JSX 要素を定義できる:

declare module "typedoc" {
  namespace JSX.JSX {
    interface IntrinsicElements {
      "custom-button": IntrinsicAttributes & {
        target: string;
      };
    }
    interface IntrinsicAttributes {
      customGlobalAttribute?: string;
    }
  }
}

コード例

フックの使用

import { Application, JSX } from "typedoc";

export function load(app: Application) {
  // <head> にスクリプトを注入
  app.renderer.hooks.on("head.end", () => (
    <script>
      <JSX.Raw html="alert('hi!');" />
    </script>
  ));

  // フッターにカスタムコンテンツを追加
  app.renderer.hooks.on("footer.end", () => (
    <div class="custom-footer">
      <p>Custom footer content</p>
    </div>
  ));
}

非同期ジョブの使用

import { Application, RendererEvent } from "typedoc";

export function load(app: Application) {
  app.renderer.preRenderAsyncJobs.push(async (output: RendererEvent) => {
    app.logger.info("Pre render, no docs written yet");
    // 外部リソースの取得など
  });

  app.renderer.postRenderAsyncJobs.push(async (output: RendererEvent) => {
    app.logger.info("Post render, all docs written");
    // 追加ファイルの生成など
  });
}

完全なカスタムテーマの例

import {
  Application,
  DefaultTheme,
  DefaultThemeRenderContext,
  PageEvent,
  Reflection,
  JSX,
} from "typedoc";

class CustomContext extends DefaultThemeRenderContext {
  // ナビゲーションのカスタマイズ
  override navigation = (context: DefaultThemeRenderContext) => {
    return (
      <nav class="custom-nav">
        {/* カスタムナビゲーション */}
      </nav>
    );
  };
}

class CustomTheme extends DefaultTheme {
  getRenderContext(pageEvent: PageEvent<Reflection>): CustomContext {
    return new CustomContext(this, pageEvent, this.application.options);
  }
}

export function load(app: Application) {
  app.renderer.defineTheme("custom", CustomTheme);
}

注意点

• テンプレートメソッドで this を使用する場合は必ずバインドすること
• DefaultThemeRenderContext を継承する際、テンプレート関数はアロー関数またはバインド済み関数として定義する
• フックはプラグインが HTML を安全に注入するための推奨方法
• JSX.Raw を使用するとエスケープされない HTML を直接挿入できる
• カスタムテーマは typedoc.json の theme オプションで指定する

関連

• プラグイン開発
• Renderer クラス
• イベントシステム

TypeDoc 国際化 (Internationalization)

TypeDoc v0.26 で導入された国際化機能。コンソール出力と生成される HTML/JSON の言語を制御する。

詳細説明

--lang オプション

--lang オプションでコンソール出力と生成されるドキュメントの言語を指定する:

typedoc --lang ja

{
  "lang": "ja"
}

ロケールの構造

ロケールファイルは src/lib/internationalization/locales ディレクトリに格納される。デフォルトの英語ロケールは src/lib/internationalization/translatable.ts に定義されている。

ロケールファイルの形式

import { buildTranslation } from "../translatable";

export = buildTranslation({
  docs_generated_at_0: "ドキュメントは {0} に生成されました",
  // 他の翻訳キー...
});

新しいロケールの追加

1. src/lib/internationalization/locales に新しいファイルを作成 2. buildTranslation() を使用して完全な翻訳を提供するか、buildIncompleteTranslation() を使用して部分的な翻訳を提供する 3. 未翻訳の文字列は自動的に英語にフォールバックする

完全な翻訳

import { buildTranslation } from "../translatable";

export = buildTranslation({
  docs_generated_at_0: "ドキュメントは {0} に生成されました",
  kind_class: "クラス",
  kind_function: "関数",
  // すべてのキーを含める
});

部分的な翻訳

import { buildIncompleteTranslation } from "../translatable";

export = buildIncompleteTranslation({
  docs_generated_at_0: "ドキュメントは {0} に生成されました",
  // 一部のキーのみ
});

プレースホルダー構文

翻訳キー名の末尾の数字はプレースホルダーの数を示す:

• docs_generated_at_0 — {0} プレースホルダー 1 つ
• tag_param_0_is_not_defined_1 — {0} と {1} の 2 つのプレースホルダー

翻訳文字列では {n} 形式でプレースホルダーを使用:

{
  docs_generated_at_0: "Documentation generated at {0}",
  tag_param_0_is_not_defined_1: "Parameter {0} is not defined in {1}",
}

バリデーション

buildTranslation と buildIncompleteTranslation 関数は以下を検証する:

• 翻訳文字列がデフォルトロケールと同じ数のプレースホルダーを含むこと
• デフォルトロケールに存在しないキーがないこと
• ユニットテストで未定義のプレースホルダーの使用を検出

プラグインでの翻訳可能文字列

プラグインは Application.internationalization.addTranslations() を使用して翻訳を統合できる。

手順

1. TranslatableStrings インターフェースに宣言マージを行う 2. プレースホルダー引数を配列形式で指定 3. キー名にインデックス番号を含む命名規則に従う

コード例

プラグインでの国際化

import { Application } from "typedoc";

// TranslatableStrings インターフェースの拡張
declare module "typedoc" {
  interface TranslatableStrings {
    // 引数なしの文字列
    my_plugin_greeting: [];
    // 1つの string 引数を持つ文字列
    my_plugin_found_0: [string];
    // 2つの引数を持つ文字列
    my_plugin_processed_0_of_1: [string, string];
  }
}

export function load(app: Application) {
  // デフォルト（英語）の翻訳を追加
  app.internationalization.addTranslations("en", {
    my_plugin_greeting: "Hello from my plugin",
    my_plugin_found_0: "Found {0} items",
    my_plugin_processed_0_of_1: "Processed {0} of {1} items",
  });

  // 日本語の翻訳を追加
  app.internationalization.addTranslations("ja", {
    my_plugin_greeting: "プラグインからこんにちは",
    my_plugin_found_0: "{0} 件のアイテムが見つかりました",
    my_plugin_processed_0_of_1: "{1} 件中 {0} 件を処理しました",
  });

  // 翻訳の使用
  app.converter.on("end", () => {
    const message = app.internationalization.translate(
      "my_plugin_found_0",
      "42"
    );
    app.logger.info(message);
  });
}

ロケールファイルの作成例

// src/lib/internationalization/locales/ja.ts
import { buildIncompleteTranslation } from "../translatable";

export = buildIncompleteTranslation({
  docs_generated_at_0: "ドキュメントは {0} に生成されました",
  kind_class: "クラス",
  kind_enum: "列挙型",
  kind_function: "関数",
  kind_interface: "インターフェース",
  kind_module: "モジュール",
  kind_namespace: "名前空間",
  kind_type_alias: "型エイリアス",
  kind_variable: "変数",
});

注意点

• 機械翻訳のみで不慣れな言語の翻訳を提出しないこと
• 部分的な翻訳は buildIncompleteTranslation を使用する
• 未翻訳の文字列は自動的に英語にフォールバックする
• プレースホルダーの数はキー名の末尾の数字で示される
• プラグインの翻訳キーは TranslatableStrings インターフェースの宣言マージで型安全に追加する
• ユニットテストが翻訳の整合性を検証する

関連

• プラグイン開発
• Application クラス

TypeDoc アーキテクチャ概要

TypeDoc の高レベルアーキテクチャと処理フローの解説。

詳細説明

処理パイプライン

TypeDoc は以下の段階的パイプラインに従って実行される:

1. オプション読み取り — どのプラグインをロードするか決定 2. プラグインロード — プラグインシステムを初期化 3. オプション再読み取り — プラグイン固有のオプションを取得 4. 入力ファイルの変換 (Convert) — ソースコードを「Reflection」と呼ばれる内部モデル表現に変換 (src/lib/models) 5. モデルの解決 (Resolve) — モデル間の相互参照とリンクを処理 6. モデルの出力 (Output) — HTML や JSON 形式にシリアライズ

Entry Points → Converter → Reflections → Resolver → Renderer → Output (HTML/JSON)

コンポーネント構成

コードベースは処理段階に対応する構造になっている:

コンバーター (Converter)

3つの主要変換モジュールが TypeScript の構文木を Reflection に変換する:

• `symbols.ts` — エクスポートされた ts.Symbol オブジェクトを処理
• `types.ts` — ts.Type と ts.TypeNode の変換を処理
• `jsdoc.ts` — JSDoc で宣言された型やシンボルを処理

リフレクション (Reflections)

Reflection はテーマやシリアライゼーション全体で一貫した処理を可能にする内部モデル構造。すべてのドキュメント対象要素（クラス、関数、プロパティなど）が Reflection として表現される。

主要な Reflection 階層:

Reflection (基底クラス)
├── ContainerReflection
│   ├── ProjectReflection
│   └── DeclarationReflection
│       └── ReferenceReflection
├── SignatureReflection
├── ParameterReflection
├── TypeParameterReflection
└── DocumentReflection

レンダラー (Renderer)

テーマシステムを通じて HTML を生成する。Theme クラスのインスタンスを使用し、Reflection ツリーを走査して各ページの HTML を出力する。

出力形式

• JSON 出力: JSONOutput.ProjectReflection インターフェースで定義。外部ツールから利用可能
• HTML 出力: テーマレンダリングシステムを通じて生成

コード例

import { Application } from "typedoc";

// 基本的な処理フロー
const app = await Application.bootstrapWithPlugins({
  entryPoints: ["src/index.ts"],
});

// 1. 変換: ソースコード → Reflections
const project = await app.convert();

if (project) {
  // 2. 出力: Reflections → HTML
  await app.generateDocs(project, "./docs");

  // または JSON 出力
  await app.generateJson(project, "./docs.json");
}

プラグインによるイベントリスニング

import { Application, Converter, ParameterType } from "typedoc";

export function load(app: Application) {
  // カスタムオプションの追加
  app.options.addDeclaration({
    name: "plugin-option",
    help: "Displayed when --help is passed",
    type: ParameterType.String,
    defaultValue: "",
  });

  // Converter イベントのリッスン
  app.converter.on(Converter.EVENT_RESOLVE, (context) => {
    if (app.options.getValue("plugin-option") === "something") {
      // カスタムロジック
    }
  });
}

テスト

TypeDoc は主に JSON モデル比較テストで機能を検証する。既知の仕様に対してモデルを比較し、Mocha ユニットテストで補完する。テーマの変更には、スクリーンショット比較によるビジュアルリグレッションテストも使用される。

注意点

• Converter はステップ 4 で動作し、TypeScript コンパイラの AST を Reflection モデルに変換する
• プラグインはステップ 2 の後にイベントリスナーを登録して動作をカスタマイズする
• Reflection モデルは HTML 出力と JSON 出力の両方で共通して使用される
• src/lib/converter/symbols.ts が最も中心的な変換ロジックを含む

関連

• プラグイン開発
• カスタムテーマ
• Application クラス
• Converter クラス
• Renderer クラス
• Reflections

TypeDoc プラグイン開発

TypeDoc プラグインの作成方法、イベントシステム、カスタムオプションの追加方法。

詳細説明

プラグインの基本構造

TypeDoc プラグインは load 関数をエクスポートする Node モジュール。ESM と CommonJS の両方をサポートするが、ESM が推奨される。

ESM プラグイン

import * as td from "typedoc";

export function load(app: td.Application) {
  // app, app.converter, app.renderer 等にイベントリスナーを登録
  // この関数は async にできる
}

重要: プラグインは異なる Application インスタンスに対して複数回ロードされる可能性がある（単一ロードで複数プロジェクトを変換する場合も含む）。この前提でプラグインを設計すること。

CommonJS プラグイン

const td = require("typedoc");

module.exports = {
  load(app) {
    // イベントリスナーを登録
  },
};

JS 設定ファイルからの直接参照

// typedoc.config.js
import * as td from "typedoc";

export function customPlugin(app) {
  // イベントリスナーを登録
}

const config = {
  plugin: [customPlugin],
};

export default config;

イベントシステム

プラグインは変換とレンダリング中に発火するイベントにリスナーを登録して TypeDoc の動作を変更する。イベントは以下の4つのクラスで提供される:

• Application — アプリケーションライフサイクルイベント
• Converter — 変換処理イベント
• Renderer — レンダリング処理イベント
• Serializer / Deserializer — シリアライゼーションイベント

各クラスは利用可能なイベントを記述する静的 EVENT_* プロパティを提供する。

Converter イベント

Renderer イベント

Application イベント

カスタムオプションの追加

import { Application, ParameterType } from "typedoc";

export function load(app: Application) {
  app.options.addDeclaration({
    name: "my-plugin-option",
    help: "Description displayed with --help",
    type: ParameterType.String,
    defaultValue: "default-value",
  });

  app.options.addDeclaration({
    name: "my-boolean-option",
    help: "A boolean option",
    type: ParameterType.Boolean,
    defaultValue: false,
  });

  app.options.addDeclaration({
    name: "my-enum-option",
    help: "An enum option",
    type: ParameterType.Map,
    map: new Map([
      ["value1", "Value 1"],
      ["value2", "Value 2"],
    ]),
    defaultValue: "value1",
  });
}

外部シンボルリゾルバ

サードパーティライブラリのシンボルへのリンクを解決するリゾルバを追加できる:

import { Application, Converter } from "typedoc";

export function load(app: Application) {
  app.converter.addUnknownSymbolResolver((ref, refl, part, symbolId) => {
    // リンク先の URL を返すか、undefined を返す
    if (ref.moduleSource === "some-package") {
      return `https://docs.example.com/${ref.symbolReference?.path?.[0]?.path}`;
    }
    return undefined;
  });
}

コード例

基本的なプラグイン

import {
  Application,
  Converter,
  Context,
  DeclarationReflection,
  ReflectionKind,
} from "typedoc";

export function load(app: Application) {
  // 宣言 Reflection 作成時のリスナー
  app.converter.on(
    Converter.EVENT_CREATE_DECLARATION,
    (context: Context, reflection: DeclarationReflection) => {
      if (reflection.kindOf(ReflectionKind.Class)) {
        app.logger.info(`Class found: ${reflection.name}`);
      }
    }
  );

  // 解決処理完了時のリスナー
  app.converter.on(Converter.EVENT_RESOLVE_END, (context: Context) => {
    const project = context.project;
    app.logger.info(
      `Total reflections: ${Object.keys(project.reflections).length}`
    );
  });
}

レンダリングプラグイン

import {
  Application,
  Renderer,
  PageEvent,
  RendererEvent,
  Reflection,
} from "typedoc";

export function load(app: Application) {
  // ページ生成前にコンテンツを修正
  app.renderer.on(
    Renderer.EVENT_END_PAGE,
    (page: PageEvent<Reflection>) => {
      if (page.contents) {
        page.contents = page.contents.replace(
          "</body>",
          '<script src="custom.js"></script></body>'
        );
      }
    }
  );

  // レンダリング完了後に追加ファイルを生成
  app.renderer.postRenderAsyncJobs.push(async (output: RendererEvent) => {
    // 追加の出力処理
  });
}

typedoc-plugin-mdn-links パターン

import { Application, Converter, ReferenceType } from "typedoc";

export function load(app: Application) {
  app.converter.addUnknownSymbolResolver((ref) => {
    if (ref.moduleSource !== "typescript") return;

    const name = ref.symbolReference?.path?.[0]?.path;
    if (!name) return;

    // MDN ドキュメントへのリンクを返す
    const mdnTypes: Record<string, string> = {
      Array: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array",
      Map: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Map",
      Set: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Set",
      Promise: "https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise",
    };

    return mdnTypes[name];
  });
}

注意点

• load 関数は async にすることができる
• ESM プラグインが推奨される（CommonJS では実験的機能の警告が出る場合がある）
• イベントリスナーの this は undefined にバインドされる
• Converter.EVENT_RESOLVE は各 Reflection に対して個別に発火する
• カスタムオプションは app.options.getValue("option-name") で取得する
• プラグインは typedoc.json の plugin 配列で指定するか、JS 設定ファイルで直接インポートする

関連

• アーキテクチャ概要
• カスタムテーマ
• 国際化
• Application クラス
• Converter クラス
• Renderer クラス
• イベントシステム
• Options API

Development

TypeDoc Browser Bundle

Using TypeDoc's limited API surface in the browser to deserialize and work with TypeDoc's JSON output.

詳細説明

TypeDoc exports a subset of its API via the typedoc/browser entry point. This allows you to load and work with TypeDoc's JSON output (produced by --json) in a browser environment without requiring Node.js.

Available Exports

The typedoc/browser bundle provides:

• Models -- TypeDoc's reflection model classes for navigating the project structure.
• `Serializer` / `Deserializer` -- Classes for serializing and deserializing TypeDoc's project model to/from JSON.
• `ConsoleLogger` -- A logger that writes to the browser console.
• `FileRegistry` -- A registry for tracking files referenced in the project.
• `setTranslations` -- A function to set the translation strings used by TypeDoc.

Translations

Translations must be loaded separately from typedoc/browser/<locale>. For English:

import translations from "typedoc/browser/en";

Call setTranslations(translations) before using the deserializer.

Workflow

1. Fetch the TypeDoc JSON output (produced by typedoc --json). 2. Set up translations. 3. Create a Deserializer instance. 4. Call deserializer.reviveProject() to reconstruct the project model. 5. Navigate the model using TypeDoc's reflection API.

コード例

Basic Browser Usage

import {
  ConsoleLogger,
  Deserializer,
  FileRegistry,
  setTranslations,
} from "typedoc/browser";

import translations from "typedoc/browser/en";

// Set translations before using the deserializer
setTranslations(translations);

// Fetch the JSON output produced by `typedoc --json`
const projectJson = await fetch("/path/to/docs.json").then((r) => r.json());

// Create a deserializer
const logger = new ConsoleLogger();
const deserializer = new Deserializer(logger);

// Revive the project model from JSON
const project = deserializer.reviveProject("API Docs", projectJson, {
  projectRoot: "/",
  registry: new FileRegistry(),
});

// Navigate the project model
console.log(project.getChildByName("SomeClass.property"));
console.log(project.getChildByName("SomeClass.property").type.toString());

Navigating the Project Model

import {
  ConsoleLogger,
  Deserializer,
  FileRegistry,
  setTranslations,
} from "typedoc/browser";
import translations from "typedoc/browser/en";

setTranslations(translations);

async function loadDocs(jsonUrl: string) {
  const projectJson = await fetch(jsonUrl).then((r) => r.json());

  const deserializer = new Deserializer(new ConsoleLogger());
  const project = deserializer.reviveProject("My Library", projectJson, {
    projectRoot: "/",
    registry: new FileRegistry(),
  });

  // Access top-level children
  for (const child of project.children ?? []) {
    console.log(`${child.name} (${child.kindString})`);
  }

  // Look up a specific member
  const myClass = project.getChildByName("MyClass");
  if (myClass) {
    console.log("Found:", myClass.name);
    for (const member of myClass.children ?? []) {
      console.log(`  - ${member.name}: ${member.type?.toString()}`);
    }
  }
}

loadDocs("/api/docs.json");

注意点

• The browser bundle provides a limited API surface compared to the full Node.js API. It is primarily for reading and navigating TypeDoc JSON output, not for generating documentation.
• You must call setTranslations() before using the Deserializer, otherwise the deserialized model may have missing or incorrect string values.
• The JSON file must be produced by TypeDoc's --json output option. Arbitrary JSON will not work.
• The projectRoot option in reviveProject is used for resolving relative file paths in the model. In a browser context, "/" is typically sufficient.
• The FileRegistry is required for tracking file references within the project model.

関連

• Installation & CLI Usage
• Node Module API
• Doc Comments Guide

TypeDoc Installation & CLI Usage

TypeDoc is a documentation generator for TypeScript projects. It converts comments in TypeScript source code into rendered HTML documentation or a JSON model.

詳細説明

Requirements

• Node.js: Current LTS version or newer is required.
• TypeScript: TypeDoc aims to support the two latest TypeScript releases for the current release.

Installation

Install TypeDoc as a local dev dependency (recommended):

npm install typedoc --save-dev

Global installation is also possible but may cause plugin/theme resolution issues unless --legacy-peer-deps is used:

npm install -g typedoc

CLI Basic Usage

The basic syntax is:

typedoc path/to/entry.ts

Common entry point example:

typedoc --entryPoints src/index.ts --out docs

Key CLI Options

TypeDoc has 100+ CLI options. The most commonly used ones:

Entry Point Strategies

Output & Appearance Options

Source & Git Options

Exclusion Options

Validation & Warning Options

Comment & Tag Options

Navigation & Organization Options

Other Options

Syntax Highlighting

TypeDoc supports 200+ languages for code highlighting (via Shiki), including: javascript, typescript, python, java, c++, rust, go, and many more.

Over 60 highlighting themes are available, including: github-dark, dracula, nord, rose-pine, tokyo-night, synthwave-84.

コード例

// Basic usage
// typedoc --entryPoints src/index.ts --out docs

// Multiple entry points
// typedoc --entryPoints src/index.ts --entryPoints src/secondary.ts --out docs

// With specific theme and readme
// typedoc --entryPoints src/index.ts --out docs --theme default --readme README.md

// Output JSON instead of HTML
// typedoc --entryPoints src/index.ts --json docs/api.json

// Watch mode for development
// typedoc --entryPoints src/index.ts --out docs --watch

// Skip type checking for faster builds
// typedoc --entryPoints src/index.ts --out docs --skipErrorChecking

// Show resolved configuration
// typedoc --showConfig

Configuration via typedoc.json

{
  "$schema": "https://typedoc.org/schema.json",
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "name": "My Project",
  "readme": "README.md",
  "theme": "default",
  "excludePrivate": true,
  "excludeExternals": true,
  "plugin": ["typedoc-plugin-markdown"],
  "sort": ["alphabetical"],
  "categorizeByGroup": true,
  "navigation": {
    "includeCategories": true,
    "includeGroups": true
  }
}

Configuration via tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext"
  },
  "typedocOptions": {
    "entryPoints": ["src/index.ts"],
    "out": "docs"
  }
}

Configuration via package.json

{
  "typedocOptions": {
    "entryPoints": ["src/index.ts"],
    "out": "docs"
  }
}

注意点

• Global installation may cause plugin/theme resolution issues; prefer local installation.
• TypeDoc reads configuration from typedoc.json, tsconfig.json, and package.json in that order.
• The --options flag specifies a custom JSON config file path (defaults to typedoc.json in the current directory).
• The --tsconfig flag specifies a custom tsconfig.json path (defaults to tsconfig.json in the current directory).
• Using --excludeNotDocumented can significantly reduce output for large projects.
• The --skipErrorChecking option can speed up generation but may produce incomplete docs if there are type errors.
• Indentation-based code blocks in comments will NOT prevent tags from being parsed. Use fenced code blocks (triple backticks) instead.

関連

• Node Module API
• Browser Bundle
• Doc Comments Guide
• JSDoc Support

TypeDoc Node Module API

How to use TypeDoc programmatically from Node.js to generate documentation, convert projects, and produce JSON or HTML output.

詳細説明

TypeDoc can be used as a Node.js module rather than through the CLI. The primary entry point is the Application class, which provides methods to bootstrap the application, convert TypeScript projects into a documentation model, and generate output.

Application Bootstrap Methods

There are two bootstrap methods:

1. `Application.bootstrapWithPlugins(options)` -- Bootstraps TypeDoc with plugin loading. This is the recommended method for most use cases. It loads all installed plugins (or those specified in the plugin option) and applies their configurations.

2. `Application.bootstrap(options)` -- Bootstraps TypeDoc without loading plugins. Use this when you want full control over which plugins are loaded, or when running TypeDoc in an environment where plugin loading is not desired. It also accepts an optional array of option readers if you want to disable TypeDoc's tsconfig.json / package.json / typedoc.json option readers.

Core Workflow

The programmatic workflow follows these steps:

1. Bootstrap the application with options. 2. Convert the entry points into a project reflection using app.convert(). 3. Generate output using one of the output methods.

Output Methods

• `app.generateOutputs(project)` -- Generates all configured outputs (HTML, JSON, etc.) based on the options provided during bootstrap.
• `app.generateDocs(project, outputDir)` -- Generates HTML documentation to a specific output directory.
• `app.generateJson(project, outputPath)` -- Generates a JSON file describing the project to a specific path.

コード例

Basic Programmatic Usage

import * as td from "typedoc";

async function main() {
  // Bootstrap with plugins (recommended)
  const app = await td.Application.bootstrapWithPlugins({
    entryPoints: ["src/index.ts"],
  });

  // Convert the project
  const project = await app.convert();

  if (project) {
    // Generate all configured outputs
    await app.generateOutputs(project);
  }
}

main().catch(console.error);

Generate HTML and JSON Separately

import * as td from "typedoc";

async function main() {
  const app = await td.Application.bootstrapWithPlugins({
    entryPoints: ["src/index.ts"],
  });

  const project = await app.convert();

  if (project) {
    // Generate HTML docs to a specific directory
    await app.generateDocs(project, "docs");

    // Generate JSON output to a specific file
    await app.generateJson(project, "docs/docs.json");
  }
}

main().catch(console.error);

Bootstrap Without Plugins

import * as td from "typedoc";

async function main() {
  // Bootstrap without plugins for full control
  const app = await td.Application.bootstrap({
    entryPoints: ["src/index.ts"],
    tsconfig: "tsconfig.json",
    excludePrivate: true,
    excludeExternals: true,
  });

  const project = await app.convert();

  if (project) {
    await app.generateOutputs(project);
  }
}

main().catch(console.error);

Passing Multiple Options

import * as td from "typedoc";

async function main() {
  const app = await td.Application.bootstrapWithPlugins({
    entryPoints: ["src/index.ts", "src/secondary.ts"],
    out: "docs",
    json: "docs/api.json",
    name: "My Library",
    readme: "README.md",
    excludePrivate: true,
    excludeNotDocumented: true,
    theme: "default",
    sort: ["alphabetical"],
    skipErrorChecking: true,
  });

  const project = await app.convert();

  if (project) {
    await app.generateOutputs(project);
  }
}

main().catch(console.error);

Error Handling

import * as td from "typedoc";

async function main() {
  const app = await td.Application.bootstrapWithPlugins({
    entryPoints: ["src/index.ts"],
  });

  const project = await app.convert();

  if (!project) {
    console.error("TypeDoc conversion failed. Check entry points and tsconfig.");
    process.exit(1);
  }

  await app.generateOutputs(project);
  console.log("Documentation generated successfully.");
}

main().catch((err) => {
  console.error("Unexpected error:", err);
  process.exit(1);
});

注意点

• Always check that app.convert() returns a non-null project before generating output. A null result indicates conversion failure.
• Application.bootstrapWithPlugins is preferred over Application.bootstrap unless you need to avoid loading plugins.
• Application.bootstrap also accepts an array of option readers if you want to disable TypeDoc's default config file readers (tsconfig.json, package.json, typedoc.json).
• The options passed to bootstrapWithPlugins / bootstrap mirror the CLI options (without the -- prefix).
• generateOutputs respects the emit option and all configured output destinations.
• generateDocs and generateJson are convenience methods for targeting specific output types directly.

関連

• Installation & CLI Usage
• Browser Bundle
• Doc Comments Guide

Getting Started

guides

Options: Configuration

TypeDoc の Configuration オプション一覧。

options

Type: string Default: 自動検出（typedoc.json, typedoc.jsonc, typedoc.config.js, typedoc.config.cjs, typedoc.config.mjs, .config/typedoc.* など） CLI: --options <filename>

コマンドラインオプションに対応するエントリを含む設定ファイルを指定する。extends キーを使用して、現在のオプションをインポートする前に追加ファイルを読み込むことができる。

サポートされるファイル形式:

• JSON ファイル: JSONC として解析される（末尾カンマとコメントを許可）。$schema キーを含めることを推奨: "https://typedoc.org/schema.json"
• JavaScript ファイル: オプションキーを持つオブジェクトをエクスポートする

{
  "$schema": "https://typedoc.org/schema.json",
  "entryPoints": ["./src/index.ts"],
  "out": "docs"
}

tsconfig

Type: string Default: カレントディレクトリと親ディレクトリを検索（tsc と同様） CLI: --tsconfig <path>

オプションを読み取るための tsconfig.json ファイルを指定する。TypeDoc は "typedocOptions" キーを読み取り、同じディレクトリ内の tsdoc.json を探す。

{
  "tsconfig": "./tsconfig.json"
}

compilerOptions

Type: object Default: なし CLI: なし（設定ファイル専用）

ドキュメント生成のために TypeScript コンパイラオプションを選択的にオーバーライドする。値は tsconfig.json のものをオーバーライドする。

{
  "compilerOptions": {
    "strict": true,
    "moduleResolution": "node"
  }
}

plugin

Type: string[] Default: なし（プラグインは読み込まれない） CLI: --plugin <name>（繰り返し可）

読み込むプラグインを指定する。npm パッケージまたはローカルファイルを参照できる。JavaScript 設定ファイルでは関数を直接指定することもできる。

{
  "plugin": ["typedoc-plugin-markdown", "./my-plugin.js"]
}

関連

• Options: Input
• Options: Output
• Options: Comments
• Options: Organization
• Options: Validation
• Options: Other

plugins