0
# TypeScript Conversion
1

2
Converter system that transforms TypeScript source code, symbols, and AST nodes into TypeDoc's reflection model, handling all aspects of TypeScript analysis and documentation extraction.
3

4
## Capabilities
5

6
### Converter Class
7

8
Main converter that orchestrates the transformation from TypeScript source code to TypeDoc's documentation model.
9

10
```typescript { .api }
11
/**
12
 * The Converter manages the conversion process from TypeScript to TypeDoc reflections.
13
 * It coordinates symbol analysis, comment parsing, and reflection creation.
14
 */
15
class Converter extends AbstractComponent<Application, ConverterEvents> {
16
  /** Owner application */
17
  readonly owner: Application;
18
  
19
  /**
20
   * Convert entry points to a project reflection
21
   * @param entryPoints - Documentation entry points to convert
22
   * @returns Project reflection or undefined if conversion fails
23
   */
24
  convert(entryPoints: readonly DocumentationEntryPoint[]): ProjectReflection | undefined;
25
  
26
  /**
27
   * Convert a TypeScript symbol to a reflection
28
   * @param context - Current conversion context
29
   * @param symbol - TypeScript symbol to convert
30
   * @param exportSymbol - Export symbol if different from main symbol
31
   * @returns Created reflection or undefined
32
   */
33
  convertSymbol(
34
    context: Context,
35
    symbol: ts.Symbol,
36
    exportSymbol?: ts.Symbol
37
  ): Reflection | undefined;
38
  
39
  /**
40
   * Convert a TypeScript type to TypeDoc type representation
41
   * @param context - Current conversion context
42
   * @param type - TypeScript type to convert
43
   * @param node - Optional AST node for context
44
   * @returns TypeDoc type representation
45
   */
46
  convertType(context: Context, type: ts.Type, node?: ts.Node): Type;
47
}
48
```
49

50
**Usage Examples:**
51

52
```typescript
53
import { Application, Context } from "typedoc";
54

55
const app = await Application.bootstrap({
56
  entryPoints: ["src/index.ts"],
57
});
58

59
// Access the converter
60
const converter = app.converter;
61

62
// Convert the project
63
const project = converter.convert([
64
  { displayName: "My Project", entryPoints: ["src/index.ts"] }
65
]);
66

67
if (project) {
68
  console.log(`Converted project: ${project.name}`);
69
  console.log(`Found ${project.children?.length} top-level declarations`);
70
}
71
```
72

73
### Conversion Context
74

75
Context object that maintains state during the conversion process and provides utilities for reflection creation.
76

77
```typescript { .api }
78
/**
79
 * Context maintains state during conversion and provides utilities for reflection creation
80
 */
81
class Context {
82
  /** Current TypeScript program */
83
  readonly program: ts.Program;
84
  /** Project being built */
85
  readonly project: ProjectReflection;
86
  /** Current conversion scope */
87
  readonly scope: Reflection;
88
  /** Current logger */
89
  readonly logger: Logger;
90
  /** Type checker instance */
91
  readonly checker: ts.TypeChecker;
92
  /** Converter instance */
93
  readonly converter: Converter;
94
  
95
  /**
96
   * Create a new declaration reflection
97
   * @param kind - Reflection kind
98
   * @param symbol - TypeScript symbol
99
   * @param exportSymbol - Export symbol if different
100
   * @param name - Override name
101
   * @returns Created declaration reflection
102
   */
103
  createDeclarationReflection(
104
    kind: ReflectionKind,
105
    symbol?: ts.Symbol,
106
    exportSymbol?: ts.Symbol,
107
    name?: string
108
  ): DeclarationReflection;
109
  
110
  /**
111
   * Finalize a declaration reflection after all processing
112
   * @param reflection - Reflection to finalize
113
   */
114
  finalizeDeclarationReflection(reflection: DeclarationReflection): void;
115
  
116
  /**
117
   * Create a signature reflection
118
   * @param kind - Signature kind
119
   * @param signature - TypeScript signature
120
   * @param parent - Parent reflection
121
   * @returns Created signature reflection
122
   */
123
  createSignatureReflection(
124
    kind: ReflectionKind,
125
    signature: ts.Signature,
126
    parent?: Reflection
127
  ): SignatureReflection;
128
  
129
  /**
130
   * Create a parameter reflection
131
   * @param parameter - TypeScript parameter symbol
132
   * @param signature - Parent signature
133
   * @returns Created parameter reflection
134
   */
135
  createParameterReflection(
136
    parameter: ts.Symbol,
137
    signature: SignatureReflection
138
  ): ParameterReflection;
139
  
140
  /**
141
   * Create a type parameter reflection
142
   * @param typeParameter - TypeScript type parameter
143
   * @param parent - Parent reflection
144
   * @returns Created type parameter reflection
145
   */
146
  createTypeParameterReflection(
147
    typeParameter: ts.TypeParameterDeclaration,
148
    parent: Reflection
149
  ): TypeParameterReflection;
150
  
151
  /**
152
   * Register reflection in the project
153
   * @param reflection - Reflection to register
154
   * @param symbol - Associated TypeScript symbol
155
   */
156
  registerReflection(reflection: Reflection, symbol?: ts.Symbol): void;
157
  
158
  /**
159
   * Get or create a reflection for a symbol
160
   * @param symbol - TypeScript symbol
161
   * @param kind - Expected reflection kind
162
   * @returns Existing or newly created reflection
163
   */
164
  expectReflection(symbol: ts.Symbol, kind?: ReflectionKind): Reflection;
165
  
166
  /**
167
   * Create child context for nested conversion
168
   * @param reflection - New scope reflection
169
   * @returns Child context
170
   */
171
  withScope(reflection: Reflection): Context;
172
}
173
```
174

175
**Usage Examples:**
176

177
```typescript
178
import { Context, ReflectionKind } from "typedoc";
179

180
// In converter plugin or custom processing
181
function processSymbol(context: Context, symbol: ts.Symbol) {
182
  // Create reflection for the symbol
183
  const reflection = context.createDeclarationReflection(
184
    ReflectionKind.Function,
185
    symbol
186
  );
187
  
188
  // Process signatures if it's a callable
189
  const signatures = context.checker.getSignaturesOfType(
190
    context.checker.getTypeOfSymbolAtLocation(symbol, symbol.valueDeclaration!),
191
    ts.SignatureKind.Call
192
  );
193
  
194
  for (const signature of signatures) {
195
    const sigReflection = context.createSignatureReflection(
196
      ReflectionKind.CallSignature,
197
      signature,
198
      reflection
199
    );
200
    
201
    // Process parameters
202
    for (const parameter of signature.parameters) {
203
      const paramReflection = context.createParameterReflection(
204
        parameter,
205
        sigReflection
206
      );
207
    }
208
  }
209
  
210
  // Finalize the reflection
211
  context.finalizeDeclarationReflection(reflection);
212
  
213
  return reflection;
214
}
215
```
216

217
### Type Conversion
218

219
Utilities for converting TypeScript type information to TypeDoc's type representations.
220

221
```typescript { .api }
222
/**
223
 * Convert default value expression to string representation
224
 * @param context - Conversion context
225
 * @param node - TypeScript node with default value
226
 * @returns String representation of default value
227
 */
228
function convertDefaultValue(context: Context, node: ts.Node): string | undefined;
229

230
/**
231
 * Convert TypeScript expression to TypeDoc representation
232
 * @param context - Conversion context  
233
 * @param node - Expression node to convert
234
 * @returns Converted expression representation
235
 */
236
function convertExpression(context: Context, node: ts.Expression): string;
237
```
238

239
### Comment Processing
240

241
Configuration and utilities for parsing JSDoc and TypeScript comments.
242

243
```typescript { .api }
244
/**
245
 * Configuration for comment parsing behavior
246
 */
247
interface CommentParserConfig {
248
  /** Block comment parsing settings */
249
  blockTags: Set<`@${string}`>;
250
  /** Inline tag parsing settings */
251
  inlineTags: Set<`@${string}`>;
252
  /** Modifier tag recognition */
253
  modifierTags: Set<`@${string}`>;
254
  /** Tag name validation */
255
  supportForTags: Set<`@${string}`>;
256
  /** JSDoc compatibility mode */
257
  jsDocCompatibility: JsDocCompatibility;
258
}
259

260
/**
261
 * JSDoc compatibility settings
262
 */
263
interface JsDocCompatibility {
264
  /** Default tag handling */
265
  defaultTag: boolean;
266
  /** Ignore unescaped braces */
267
  ignoreUnescapedBraces: boolean;
268
}
269
```
270

271
### External Symbol Resolution
272

273
System for resolving references to external packages and symbols.
274

275
```typescript { .api }
276
/**
277
 * Interface for resolving external symbols not in the current project
278
 */
279
interface ExternalSymbolResolver {
280
  /**
281
   * Resolve an external symbol reference
282
   * @param declaration - Declaration reference to resolve
283
   * @param referencingModule - Module making the reference
284
   * @param symbolId - Symbol identifier
285
   * @returns Resolution result or undefined if not resolvable
286
   */
287
  resolveSymbol(
288
    declaration: DeclarationReference,
289
    referencingModule: Reflection,
290
    symbolId?: ReflectionSymbolId
291
  ): ExternalResolveResult | undefined;
292
}
293

294
/**
295
 * Result of external symbol resolution
296
 */
297
interface ExternalResolveResult {
298
  /** Target reflection if resolved internally */
299
  target?: Reflection;
300
  /** External package name */
301
  package?: string;
302
  /** URL to external documentation */
303
  url?: string;
304
}
305
```
306

307
### Converter Events
308

309
Events fired during the conversion process for plugin integration and custom processing.
310

311
```typescript { .api }
312
/**
313
 * Events dispatched during conversion process
314
 */
315
interface ConverterEvents {
316
  /** Begin conversion process */
317
  BEGIN: [Context];
318
  /** End conversion process */
319
  END: [Context];
320
  /** Begin converting a source file */
321
  FILE_BEGIN: [Context, Reflection, ts.SourceFile];
322
  /** Create a declaration reflection */
323
  CREATE_DECLARATION: [Context, DeclarationReflection, ts.Declaration | undefined];
324
  /** Create a signature reflection */
325
  CREATE_SIGNATURE: [Context, SignatureReflection, ts.Signature | ts.JSDocSignature, ts.Node | undefined];
326
  /** Create a parameter reflection */
327
  CREATE_PARAMETER: [Context, ParameterReflection, ts.Symbol, ts.Node | undefined];
328
  /** Create a type parameter reflection */
329
  CREATE_TYPE_PARAMETER: [Context, TypeParameterReflection, ts.TypeParameterDeclaration];
330
  /** Resolve external symbol */
331
  RESOLVE_EXTERNAL_SYMBOL: [Context, DeclarationReference, ReflectionSymbolId];
332
}
333
```
334

335
**Usage Examples:**
336

337
```typescript
338
import { Application, ConverterEvents } from "typedoc";
339

340
const app = await Application.bootstrap();
341

342
// Listen for conversion events
343
app.converter.on("BEGIN", (context) => {
344
  console.log("Starting conversion");
345
});
346

347
app.converter.on("CREATE_DECLARATION", (context, reflection, declaration) => {
348
  console.log(`Created ${reflection.kind} reflection: ${reflection.name}`);
349
  
350
  // Custom processing for specific declaration types
351
  if (reflection.kind === ReflectionKind.Class) {
352
    // Add custom metadata or processing for classes
353
    reflection.comment = reflection.comment || new Comment();
354
  }
355
});
356

357
app.converter.on("END", (context) => {
358
  console.log("Conversion completed");
359
  console.log(`Total reflections: ${context.project.children?.length}`);
360
});
361
```
362

363
### Converter Plugins
364

365
Base class and utilities for creating converter plugins.
366

367
```typescript { .api }
368
/**
369
 * Base class for converter components/plugins
370
 */
371
abstract class ConverterComponent extends AbstractComponent<Application, ConverterEvents> {
372
  /** Converter instance */
373
  readonly converter: Converter;
374
  
375
  /**
376
   * Initialize the component
377
   */
378
  initialize(): void;
379
  
380
  /**
381
   * Called when component is removed
382
   */
383
  remove(): void;
384
}
385
```
386

387
**Usage Examples:**
388

389
```typescript
390
import { ConverterComponent, ReflectionKind } from "typedoc";
391

392
class CustomConverterPlugin extends ConverterComponent {
393
  initialize() {
394
    // Listen for declaration creation
395
    this.listenTo(this.owner, "CREATE_DECLARATION", this.onCreateDeclaration);
396
  }
397
  
398
  private onCreateDeclaration = (context: Context, reflection: DeclarationReflection) => {
399
    // Add custom processing for functions
400
    if (reflection.kind === ReflectionKind.Function) {
401
      // Extract custom metadata from JSDoc tags
402
      const customTag = reflection.comment?.getTag("@custom");
403
      if (customTag) {
404
        // Process custom tag content
405
        console.log(`Custom tag found on ${reflection.name}`);
406
      }
407
    }
408
  };
409
}
410

411
// Register the plugin
412
app.converter.addComponent("custom-plugin", CustomConverterPlugin);
413
```
414

415
## Node and Symbol Utilities
416

417
### TypeScript Integration
418

419
```typescript { .api }
420
/**
421
 * Utility functions for TypeScript node analysis
422
 */
423
namespace NodeUtils {
424
  /** Check if node is exported */
425
  function isExported(node: ts.Node): boolean;
426
  
427
  /** Check if node is namespace export */
428
  function isNamespaceExport(node: ts.Node): boolean;
429
  
430
  /** Get name from various node types */
431
  function getName(node: ts.Node): string | undefined;
432
  
433
  /** Check if node has specific modifier */
434
  function hasModifier(node: ts.Node, modifier: ts.SyntaxKind): boolean;
435
}
436

437
/**
438
 * Utility functions for TypeScript symbol analysis
439
 */
440
namespace SymbolUtils {
441
  /** Get qualified symbol name */
442
  function getQualifiedName(symbol: ts.Symbol, checker: ts.TypeChecker): string;
443
  
444
  /** Check if symbol is alias */
445
  function isAlias(symbol: ts.Symbol): boolean;
446
  
447
  /** Resolve alias to target symbol */
448
  function resolveAlias(symbol: ts.Symbol, checker: ts.TypeChecker): ts.Symbol;
449
}
450
```
451

452
## Error Handling
453

454
The converter system handles various error conditions:
455

456
- **Compilation Errors**: TypeScript compiler diagnostics and parsing failures
457
- **Symbol Resolution**: Missing exports, circular dependencies, external references  
458
- **Type Analysis**: Complex type constructs, generic constraints, conditional types
459
- **Comment Parsing**: Malformed JSDoc, unsupported tags, link resolution failures
460
- **Memory Management**: Large projects, deep nesting, complex inheritance hierarchies
461

462
All errors are logged through the application's logger with appropriate severity levels and context information.