0
# Documentation Models
1

2
Complete object model representing TypeScript documentation elements including reflections, types, comments, source references, and the hierarchical structure of TypeScript projects.
3

4
## Capabilities
5

6
### Core Reflection Types
7

8
Base reflection classes that represent different kinds of TypeScript declarations and documentation elements.
9

10
```typescript { .api }
11
/**
12
 * Base class for all reflections representing documented elements
13
 */
14
abstract class Reflection {
15
  /** Unique identifier for this reflection */
16
  readonly id: ReflectionId;
17
  /** The name of this reflection */
18
  readonly name: string;
19
  /** The kind of reflection */
20
  readonly kind: ReflectionKind;
21
  /** Flags describing reflection properties */
22
  readonly flags: ReflectionFlag;
23
  /** Associated comment documentation */
24
  comment?: Comment;
25
  /** Parent reflection in the hierarchy */
26
  readonly parent?: Reflection;
27
  /** Original TypeScript symbol */
28
  readonly symbol?: ts.Symbol;
29
  /** Source file location */
30
  sources?: SourceReference[];
31
  /** Reflection groups for organization */
32
  groups?: ReflectionGroup[];
33
  /** Reflection categories for organization */
34
  categories?: ReflectionCategory[];
35

36
  /** Get full name including parent hierarchy */
37
  getFullName(separator?: string): string;
38
  /** Get URL for this reflection */
39
  getUrl(): string;
40
  /** Check if reflection has specific flag */
41
  hasFlag(flag: ReflectionFlag): boolean;
42
  /** Set comment for this reflection */
43
  setComment(comment: Comment): void;
44
}
45

46
/**
47
 * Reflection that can contain child reflections
48
 */
49
abstract class ContainerReflection extends Reflection {
50
  /** Child reflections */
51
  children?: DeclarationReflection[];
52
  /** Groups organizing child reflections */
53
  groups?: ReflectionGroup[];
54
  /** Categories for organizing reflections */  
55
  categories?: ReflectionCategory[];
56

57
  /** Get child reflection by name */
58
  getChildByName(name: string): Reflection | undefined;
59
  /** Get all children matching predicate */
60
  getChildren(predicate?: (child: Reflection) => boolean): Reflection[];
61
  /** Add child reflection */
62
  addChild(child: DeclarationReflection): void;
63
  /** Remove child reflection */
64
  removeChild(child: DeclarationReflection): void;
65
}
66

67
/**
68
 * Root reflection representing the entire project
69
 */
70
class ProjectReflection extends ContainerReflection {
71
  /** Package version from package.json */
72
  readonly packageVersion?: string;
73
  /** README content */
74
  readonly readme?: string;
75
  /** Changelog content */
76
  readonly changelog?: string;
77
  /** Entry points for this project */
78
  readonly entryPoints: readonly DocumentationEntryPoint[];
79
  /** File registry tracking all source files */
80
  readonly files: FileRegistry;
81

82
  /** Get reflection by ID */
83
  getReflectionById(id: ReflectionId): Reflection | undefined;
84
}
85

86
/**
87
 * Reflection for TypeScript declarations (classes, functions, variables, etc.)
88
 */
89
class DeclarationReflection extends ContainerReflection {
90
  /** Type of this declaration */
91
  type?: Type;
92
  /** Default value as string */
93
  defaultValue?: string;
94
  /** Reference to overwritten declaration */
95
  overwrites?: ReferenceType;
96
  /** Reference to inherited declaration */
97
  inheritedFrom?: ReferenceType;
98
  /** Reference to implemented interface member */
99
  implementationOf?: ReferenceType;
100
  /** Types this declaration extends */
101
  extendedTypes?: Type[];
102
  /** Types that extend this declaration */
103
  extendedBy?: ReferenceType[];
104
  /** Types this declaration implements */
105
  implementedTypes?: Type[];
106
  /** Types that implement this declaration */
107
  implementedBy?: ReferenceType[];
108
  /** Type parameters for generic declarations */
109
  typeParameters?: TypeParameterReflection[];
110
  /** Signatures for callable declarations */
111
  signatures?: SignatureReflection[];
112
  /** Index signature if present */
113
  indexSignature?: SignatureReflection;
114
  /** Get signature for accessors */
115
  getSignature?: SignatureReflection;
116
  /** Set signature for accessors */
117
  setSignature?: SignatureReflection;
118
  /** Variant information */
119
  variant?: ReflectionVariant;
120

121
  /** Check if declaration is exported */
122
  isExported(): boolean;
123
  /** Get all signatures including inherited ones */
124
  getAllSignatures(): SignatureReflection[];
125
}
126
```
127

128
**Usage Examples:**
129

130
```typescript
131
import { ProjectReflection, DeclarationReflection, ReflectionKind } from "typedoc";
132

133
// Access project information
134
const project: ProjectReflection = app.convert();
135
console.log(`Project: ${project.name} v${project.packageVersion}`);
136
console.log(`Entry points: ${project.entryPoints.length}`);
137

138
// Find specific declarations
139
const classes = project.getChildren().filter(child => 
140
  child.kind === ReflectionKind.Class
141
);
142

143
const exports = project.getChildren().filter(child => 
144
  child instanceof DeclarationReflection && child.isExported()
145
);
146

147
// Navigate reflection hierarchy
148
for (const child of project.children || []) {
149
  console.log(`${child.name} (${ReflectionKind[child.kind]})`);
150
  if (child instanceof DeclarationReflection && child.signatures) {
151
    child.signatures.forEach(sig => {
152
      console.log(`  Signature: ${sig.name}(${sig.parameters?.map(p => p.name).join(', ')})`);
153
    });
154
  }
155
}
156
```
157

158
### Function and Method Signatures
159

160
Representations of callable elements including functions, methods, constructors, and their parameters.
161

162
```typescript { .api }
163
/**
164
 * Reflection for function/method signatures
165
 */
166
class SignatureReflection extends Reflection {
167
  /** Parameters for this signature */
168
  parameters?: ParameterReflection[];
169
  /** Return type */
170
  type?: Type;
171
  /** Type parameters for generic signatures */
172
  typeParameters?: TypeParameterReflection[];
173
  /** Overwrites information */
174
  overwrites?: ReferenceType;
175
  /** Inherited from information */
176
  inheritedFrom?: ReferenceType;
177
  /** Implementation information */
178
  implementationOf?: ReferenceType;
179

180
  /** Get signature string representation */
181
  toString(): string;
182
  /** Check if signature has parameters */
183
  hasParameters(): boolean;
184
}
185

186
/**
187
 * Reflection for function/method parameters
188
 */
189
class ParameterReflection extends Reflection {
190
  /** Parameter type */
191
  type?: Type;
192
  /** Default value */
193
  defaultValue?: string;
194
  /** Rest parameter flag */
195
  rest: boolean;
196
  /** Optional parameter flag */
197
  optional: boolean;
198

199
  /** Check if parameter is optional */
200
  isOptional(): boolean;
201
  /** Check if parameter is rest parameter */
202
  isRest(): boolean;
203
}
204

205
/**
206
 * Reflection for generic type parameters
207
 */
208
class TypeParameterReflection extends Reflection {
209
  /** Constraint type */
210
  type?: Type;
211
  /** Default type */
212
  default?: Type;
213
  /** Constraint type for extends clause */
214
  constraint?: Type;
215

216
  /** Get type parameter bound */
217
  getBound(): Type | undefined;
218
}
219
```
220

221
### Type System
222

223
Comprehensive type representation system covering all TypeScript type constructs.
224

225
```typescript { .api }
226
/**
227
 * Base class for all type representations
228
 */
229
abstract class Type {
230
  /** Type discriminator */
231
  abstract readonly type: keyof TypeKindMap;
232
  
233
  /** String representation of type */
234
  toString(): string;
235
  /** Visit type with visitor pattern */
236
  visit<T>(visitor: TypeVisitor<T>): T;
237
  /** Check if type needs parentheses in context */
238
  needsParenthesis(context: TypeContext): boolean;
239
  /** Serialize type to JSON */
240
  toObject(serializer: Serializer): JSONOutput.SomeType;
241
}
242

243
/**
244
 * Reference to another type or reflection
245
 */
246
class ReferenceType extends Type {
247
  readonly type = "reference";
248
  /** Name of referenced type */
249
  name: string;
250
  /** Type arguments for generic references */
251
  typeArguments?: Type[];
252
  /** Referenced reflection if resolved */
253
  reflection?: Reflection;
254
  /** Symbol ID for external references */
255
  symbolId?: ReflectionSymbolId;
256
  /** Package name for external references */
257
  package?: string;
258

259
  /** Check if reference is resolved */
260
  isResolved(): boolean;
261
}
262

263
/**
264
 * Array type representation
265
 */
266
class ArrayType extends Type {
267
  readonly type = "array";
268
  /** Element type */
269
  elementType: Type;
270
}
271

272
/**
273
 * Union type representation  
274
 */
275
class UnionType extends Type {
276
  readonly type = "union";
277
  /** Union member types */
278
  types: Type[];
279
}
280

281
/**
282
 * Intersection type representation
283
 */
284
class IntersectionType extends Type {
285
  readonly type = "intersection"; 
286
  /** Intersection member types */
287
  types: Type[];
288
}
289

290
/**
291
 * Literal type representation
292
 */
293
class LiteralType extends Type {
294
  readonly type = "literal";
295
  /** Literal value */
296
  value: string | number | boolean | bigint | null;
297
}
298

299
/**
300
 * Intrinsic type representation (string, number, boolean, etc.)
301
 */
302
class IntrinsicType extends Type {
303
  readonly type = "intrinsic";
304
  /** Intrinsic type name */
305
  name: string;
306
}
307

308
/**
309
 * Conditional type representation (T extends U ? X : Y)
310
 */
311
class ConditionalType extends Type {
312
  readonly type = "conditional";
313
  /** Check type (T) */
314
  checkType: Type;
315
  /** Extends type (U) */
316
  extendsType: Type;
317
  /** True type (X) */
318
  trueType: Type;
319
  /** False type (Y) */
320
  falseType: Type;
321
}
322

323
/**
324
 * Mapped type representation
325
 */
326
class MappedType extends Type {
327
  readonly type = "mapped";
328
  /** Parameter name */
329
  parameter: string;
330
  /** Parameter type */
331
  parameterType: Type;
332
  /** Template type */
333
  templateType: Type;
334
  /** Readonly modifier */
335
  readonlyModifier?: "+" | "-";
336
  /** Optional modifier */
337
  optionalModifier?: "+" | "-";
338
  /** Name type for computed property names */
339
  nameType?: Type;
340
}
341

342
/**
343
 * Template literal type representation
344
 */
345
class TemplateStringType extends Type {
346
  readonly type = "templateString";
347
  /** Template head */
348
  head: string;
349
  /** Template spans */
350
  tail: [Type, string][];
351
}
352
```
353

354
### Comments and Documentation
355

356
Parsed JSDoc comments and documentation elements.
357

358
```typescript { .api }
359
/**
360
 * Parsed comment documentation
361
 */
362
class Comment {
363
  /** Summary section */
364
  summary: CommentDisplayPart[];
365
  /** Block tags (@param, @returns, etc.) */
366
  blockTags: CommentTag[];
367
  /** Modifier tags (@public, @internal, etc.) */
368
  modifierTags: Set<`@${string}`>;
369

370
  /** Get block tag by name */
371
  getTag(name: `@${string}`): CommentTag | undefined;
372
  /** Check if comment has modifier tag */
373
  hasModifier(name: `@${string}`): boolean;
374
  /** Remove block tag */
375
  removeTag(name: `@${string}`): void;
376
  /** Clone comment */
377
  clone(): Comment;
378
}
379

380
/**
381
 * Comment display part (text, code, links, etc.)
382
 */
383
interface CommentDisplayPart {
384
  /** Part kind */
385
  kind: string;
386
  /** Text content */
387
  text: string;
388
  /** Target for links */
389
  target?: Reflection | string;
390
}
391

392
/**
393
 * Block comment tag (@param, @returns, etc.)
394
 */
395
class CommentTag {
396
  /** Tag name including @ */
397
  tag: `@${string}`;
398
  /** Tag content */
399
  content: CommentDisplayPart[];
400
  /** Parameter name for @param tags */
401
  name?: string;
402
}
403
```
404

405
### Source References
406

407
Information about source code locations and file tracking.
408

409
```typescript { .api }
410
/**
411
 * Reference to source code location
412
 */
413
class SourceReference {
414
  /** Source file name */
415
  fileName: string;
416
  /** Line number (1-based) */
417
  line: number;
418
  /** Character position */
419
  character: number;
420
  /** URL to source file */
421
  url?: string;
422

423
  /** Get relative path */
424
  getRelativePath(base: string): string;
425
}
426

427
/**
428
 * Registry tracking all source files
429
 */
430
class FileRegistry {
431
  /** Add source file */
432
  addFile(file: string): void;
433
  /** Check if file is registered */
434
  hasFile(file: string): boolean;
435
  /** Get all registered files */
436
  getFiles(): string[];
437
  /** Clear registry */
438
  clear(): void;
439
}
440
```
441

442
### Organizational Types
443

444
Types for organizing and categorizing reflections.
445

446
```typescript { .api }
447
/**
448
 * Group of related reflections
449
 */
450
class ReflectionGroup {
451
  /** Group title */
452
  title: string;
453
  /** Child reflections in group */
454
  children: Reflection[];
455
  /** Categories within group */
456
  categories?: ReflectionCategory[];
457

458
  /** Get all children recursively */
459
  getAllChildrenByKind(kind: ReflectionKind): Reflection[];
460
}
461

462
/**
463
 * Category for organizing reflections
464
 */
465
class ReflectionCategory {
466
  /** Category title */
467
  title: string;  
468
  /** Child reflections in category */
469
  children: Reflection[];
470

471
  /** Get children by kind */
472
  getChildrenByKind(kind: ReflectionKind): Reflection[];
473
}
474

475
/**
476
 * Symbol ID for tracking external references
477
 */
478
class ReflectionSymbolId {
479
  /** File name */
480
  fileName: string;
481
  /** Qualified name */
482
  qualifiedName: string;
483
  /** Position in file */
484
  pos: number;
485

486
  /** Get stable string representation */
487
  getStableKey(): string;
488
}
489
```
490

491
## Enums and Constants
492

493
### Reflection Types
494

495
```typescript { .api }
496
enum ReflectionKind {
497
  Project = 0x1,
498
  Module = 0x2,
499
  Namespace = 0x4,
500
  Enum = 0x8,
501
  EnumMember = 0x10,
502
  Variable = 0x20,
503
  Function = 0x40,
504
  Class = 0x80,
505
  Interface = 0x100,
506
  Constructor = 0x200,
507
  Property = 0x400,
508
  Method = 0x800,
509
  CallSignature = 0x1000,
510
  IndexSignature = 0x2000,
511
  ConstructorSignature = 0x4000,
512
  Parameter = 0x8000,
513
  TypeLiteral = 0x10000,
514
  TypeParameter = 0x20000,
515
  Accessor = 0x40000,
516
  GetSignature = 0x80000,
517
  SetSignature = 0x100000,
518
  ObjectLiteral = 0x200000,
519
  TypeAlias = 0x400000,
520
  Reference = 0x800000,
521
  Document = 0x1000000,
522
}
523

524
enum ReflectionFlag {
525
  None = 0,
526
  Private = 1,
527
  Protected = 2,
528
  Public = 4,
529
  Static = 8,
530
  External = 16,
531
  Optional = 32,
532
  Rest = 64,
533
  Abstract = 128,
534
  Const = 256,
535
  Readonly = 512,
536
  Inherited = 1024,
537
}
538
```
539

540
### Type System Enums
541

542
```typescript { .api }
543
enum TypeContext {
544
  none,
545
  templateLiteralElement,
546
  mappedTypeParameter,
547
  conditionalCheckType,
548
  conditionalExtendsType,
549
  conditionalTrueType,
550
  conditionalFalseType,
551
  indexedAccessObjectType,
552
  indexedAccessIndexType,
553
  inferredConstraint,
554
}
555

556
interface TypeKindMap {
557
  array: ArrayType;
558
  conditional: ConditionalType;
559
  indexedAccess: IndexedAccessType;
560
  inferred: InferredType;
561
  intersection: IntersectionType;
562
  intrinsic: IntrinsicType;
563
  literal: LiteralType;
564
  mapped: MappedType;
565
  namedTupleMember: NamedTupleMemberType;
566
  optional: OptionalType;
567
  predicate: PredicateType;
568
  query: QueryType;
569
  reference: ReferenceType;
570
  reflection: ReflectionType;
571
  rest: RestType;
572
  templateString: TemplateStringType;
573
  tuple: TupleType;
574
  typeOperator: TypeOperatorType;
575
  union: UnionType;
576
  unknown: UnknownType;
577
}
578
```
579

580
## Utility Functions
581

582
### Reflection Utilities
583

584
```typescript { .api }
585
/**
586
 * Reset the global reflection ID counter (for testing)
587
 */
588
function resetReflectionID(): void;
589

590
/**
591
 * Remove reflection from its parent container
592
 */
593
function removeReflectionFromParent(reflection: Reflection): void;
594

595
/**
596
 * Split unquoted string for comment parsing
597
 */
598
function splitUnquotedString(input: string, delimiter: string): string[];
599
```