0
# AST Node Types
1

2
Comprehensive set of 45+ DocNode classes representing all parts of TSDoc comments including text, tags, code blocks, links, and HTML elements.
3

4
## Capabilities
5

6
### DocNode Base Class
7

8
Abstract base class for all AST nodes in the TSDoc syntax tree.
9

10
```typescript { .api }
11
/**
12
 * Base class for all AST nodes in the TSDoc syntax tree
13
 */
14
abstract class DocNode {
15
  /** The kind of DocNode (e.g., "DocComment", "DocParagraph") */
16
  readonly kind: string;
17
  
18
  /** Parent node in the AST, undefined for root nodes */
19
  readonly parent: DocNode | undefined;
20
  
21
  /** Get immediate child nodes, some positions may be undefined */
22
  abstract getChildNodes(): ReadonlyArray<DocNode | undefined>;
23
}
24
```
25

26
### DocComment
27

28
Root node representing an entire TSDoc comment with all its sections.
29

30
```typescript { .api }
31
/**
32
 * Root node representing an entire TSDoc comment
33
 */
34
class DocComment extends DocNode {
35
  /** The summary section (first paragraph) */
36
  readonly summarySection: DocSection;
37
  
38
  /** The @remarks block, if present */
39
  readonly remarksBlock: DocBlock | undefined;
40
  
41
  /** All @param blocks */
42
  readonly parameterBlocks: ReadonlyArray<DocParamBlock>;
43
  
44
  /** All @typeParam blocks */
45
  readonly typeParameterBlocks: ReadonlyArray<DocParamBlock>;
46
  
47
  /** The @returns block, if present */
48
  readonly returnsBlock: DocBlock | undefined;
49
  
50
  /** The {@inheritDoc} tag, if present */
51
  readonly inheritDocTag: DocInheritDocTag | undefined;
52
  
53
  /** The @deprecated block, if present */
54
  readonly deprecatedBlock: DocBlock | undefined;
55
  
56
  /** All @see blocks */
57
  readonly seeBlocks: ReadonlyArray<DocBlock>;
58
  
59
  /** All @example blocks */
60
  readonly exampleBlocks: ReadonlyArray<DocBlock>;
61
  
62
  /** Custom blocks not handled by standard properties */
63
  readonly customBlocks: ReadonlyArray<DocBlock>;
64
  
65
  /** Modifier tags like @public, @beta, @alpha */
66
  readonly modifierTagSet: StandardModifierTagSet;
67
}
68
```
69

70
**Usage Examples:**
71

72
```typescript
73
import { TSDocParser } from "@microsoft/tsdoc";
74

75
const parser = new TSDocParser();
76
const context = parser.parseString(`
77
  /**
78
   * Calculates something important.
79
   * @param value - The input value
80
   * @returns The calculated result
81
   * @beta
82
   */
83
`);
84

85
const comment = context.docComment;
86
console.log(comment.summarySection); // "Calculates something important."
87
console.log(comment.parameterBlocks.length); // 1
88
console.log(comment.modifierTagSet.isBeta); // true
89
```
90

91
### DocSection and DocParagraph
92

93
Container nodes for organizing content within comments.
94

95
```typescript { .api }
96
/**
97
 * Container for the main content of a comment section
98
 */
99
class DocSection extends DocNodeContainer {
100
  // Inherits appendNode() and getChildNodes() from DocNodeContainer
101
}
102

103
/**
104
 * Represents a paragraph of content
105
 */
106
class DocParagraph extends DocNodeContainer {
107
  // Inherits appendNode() and getChildNodes() from DocNodeContainer
108
}
109

110
/**
111
 * Base class for nodes that contain other nodes
112
 */
113
abstract class DocNodeContainer extends DocNode {
114
  /** Get all child nodes as an array */
115
  getChildNodes(): ReadonlyArray<DocNode>;
116
  
117
  /** Add a child node to this container */
118
  appendNode(docNode: DocNode): void;
119
  
120
  /** Add multiple child nodes to this container */
121
  appendNodes(docNodes: ReadonlyArray<DocNode>): void;
122
}
123
```
124

125
### DocBlock and DocBlockTag
126

127
Represents block-level tags like @remarks, @example, @param.
128

129
```typescript { .api }
130
/**
131
 * Represents a block-level tag like @remarks or @example
132
 */
133
class DocBlock extends DocNode {
134
  /** The tag portion (e.g., "@remarks") */
135
  readonly blockTag: DocBlockTag;
136
  
137
  /** The content following the tag */
138
  readonly content: DocSection;
139
}
140

141
/**
142
 * Represents the tag portion of a block tag
143
 */
144
class DocBlockTag extends DocNode {
145
  /** The tag name without the @ symbol */
146
  readonly tagName: string;
147
  
148
  /** The tag name in uppercase for case-insensitive comparison */
149
  readonly tagNameWithUpperCase: string;
150
}
151
```
152

153
### DocParamBlock
154

155
Specialized block for @param and @typeParam tags.
156

157
```typescript { .api }
158
/**
159
 * Specialized block for @param and @typeParam tags
160
 */
161
class DocParamBlock extends DocBlock {
162
  /** The parameter name being documented */
163
  readonly parameterName: string;
164
}
165

166
/**
167
 * Collection of parameter blocks with lookup methods
168
 */
169
class DocParamCollection extends DocNode {
170
  /** All parameter blocks in the collection */
171
  readonly blocks: ReadonlyArray<DocParamBlock>;
172
  
173
  /** Find a parameter block by name */
174
  tryGetBlockByName(parameterName: string): DocParamBlock | undefined;
175
}
176
```
177

178
**Usage Examples:**
179

180
```typescript
181
import { TSDocParser } from "@microsoft/tsdoc";
182

183
const parser = new TSDocParser();
184
const context = parser.parseString(`
185
  /**
186
   * @param name - The user's name
187
   * @param age - The user's age
188
   * @returns User information
189
   */
190
`);
191

192
const comment = context.docComment;
193

194
// Access parameter blocks
195
comment.parameterBlocks.forEach(paramBlock => {
196
  console.log(`Parameter: ${paramBlock.parameterName}`);
197
  console.log(`Tag: ${paramBlock.blockTag.tagName}`);
198
});
199

200
// Find specific parameter
201
const nameParam = comment.parameterBlocks.find(
202
  p => p.parameterName === "name"
203
);
204
```
205

206
### Text Content Nodes
207

208
Nodes representing different types of text content.
209

210
```typescript { .api }
211
/**
212
 * Plain text content within a comment
213
 */
214
class DocPlainText extends DocNode {
215
  /** The plain text content */
216
  readonly text: string;
217
}
218

219
/**
220
 * Inline code span (backtick-delimited)
221
 */
222
class DocCodeSpan extends DocNode {
223
  /** The code content without the backticks */
224
  readonly code: string;
225
}
226

227
/**
228
 * Fenced code block with language specification
229
 */
230
class DocFencedCode extends DocNode {
231
  /** Programming language for syntax highlighting */
232
  readonly language: string;
233
  
234
  /** The code content without the fence markers */
235
  readonly code: string;
236
}
237

238
/**
239
 * Escaped text (backslash escapes)
240
 */
241
class DocEscapedText extends DocNode {
242
  /** The original encoded text with backslashes */
243
  readonly encodedText: string;
244
  
245
  /** The decoded text with escapes resolved */
246
  readonly decodedText: string;
247
}
248

249
/**
250
 * Text that could not be parsed correctly
251
 */
252
class DocErrorText extends DocNode {
253
  /** The problematic text */
254
  readonly text: string;
255
  
256
  /** Error message ID */
257
  readonly messageId: TSDocMessageId;
258
  
259
  /** Human-readable error message */
260
  readonly errorMessage: string;
261
  
262
  /** Location of the error */
263
  readonly errorLocation: TextRange;
264
}
265

266
/**
267
 * Soft line break (newline that doesn't end a paragraph)
268
 */
269
class DocSoftBreak extends DocNode {
270
  // No additional properties - represents a soft break
271
}
272
```
273

274
### Inline Tags
275

276
Nodes representing inline tags like {@link} and {@inheritDoc}.
277

278
```typescript { .api }
279
/**
280
 * Base class for inline tags
281
 */
282
abstract class DocInlineTagBase extends DocNode {
283
  /** The tag name without braces (e.g., "link", "inheritDoc") */
284
  readonly tagName: string;
285
  
286
  /** The tag name in uppercase for comparison */
287
  readonly tagNameWithUpperCase: string;
288
}
289

290
/**
291
 * Inline {@link} tag for cross-references
292
 */
293
class DocLinkTag extends DocInlineTagBase {
294
  /** Code destination for API references */
295
  readonly codeDestination: DocCodeSpan | undefined;
296
  
297
  /** URL destination for external links */
298
  readonly urlDestination: string | undefined;
299
  
300
  /** Display text for the link */
301
  readonly linkText: string | undefined;
302
}
303

304
/**
305
 * Generic inline tag like {@label} or custom tags
306
 */
307
class DocInlineTag extends DocInlineTagBase {
308
  /** The content inside the tag braces */
309
  readonly tagContent: string;
310
}
311

312
/**
313
 * Special {@inheritDoc} tag
314
 */
315
class DocInheritDocTag extends DocInlineTagBase {
316
  /** Optional declaration reference for selective inheritance */
317
  readonly declarationReference: DocDeclarationReference | undefined;
318
}
319
```
320

321
### Declaration References
322

323
Nodes for referencing API declarations in {@link} and {@inheritDoc} tags.
324

325
```typescript { .api }
326
/**
327
 * Reference to an API declaration
328
 */
329
class DocDeclarationReference extends DocNode {
330
  /** Optional package name */
331
  readonly packageName: string | undefined;
332
  
333
  /** Optional import path */
334
  readonly importPath: string | undefined;
335
  
336
  /** Chain of member references */
337
  readonly memberReferences: ReadonlyArray<DocMemberReference>;
338
}
339

340
/**
341
 * Reference to a class member or namespace member
342
 */
343
class DocMemberReference extends DocNode {
344
  /** Member symbol (., #, ~) indicating access level */
345
  readonly memberSymbol: DocMemberSymbol | undefined;
346
  
347
  /** Member identifier (name) */
348
  readonly memberIdentifier: DocMemberIdentifier | undefined;
349
  
350
  /** Selector for overloaded members */
351
  readonly selector: DocMemberSelector | undefined;
352
}
353

354
/**
355
 * Identifier part of a member reference
356
 */
357
class DocMemberIdentifier extends DocNode {
358
  /** The identifier name */
359
  readonly identifier: string;
360
}
361

362
/**
363
 * Symbol notation in member references
364
 */
365
class DocMemberSymbol extends DocNode {
366
  /** The symbol text (., #, or ~) */
367
  readonly symbolText: string;
368
}
369

370
/**
371
 * Selector for overloaded members
372
 */
373
class DocMemberSelector extends DocNode {
374
  /** The selector text */
375
  readonly selector: string;
376
}
377
```
378

379
### HTML Elements
380

381
Nodes representing HTML tags within comments.
382

383
```typescript { .api }
384
/**
385
 * HTML start tag like <b> or <a href="...">
386
 */
387
class DocHtmlStartTag extends DocNode {
388
  /** Tag name (e.g., "b", "a") */
389
  readonly name: string;
390
  
391
  /** Spacing after the tag name */
392
  readonly spacingAfterName: string | undefined;
393
  
394
  /** HTML attributes */
395
  readonly htmlAttributes: ReadonlyArray<DocHtmlAttribute>;
396
  
397
  /** Whether this is a self-closing tag */
398
  readonly selfClosingTag: boolean;
399
}
400

401
/**
402
 * HTML end tag like </b>
403
 */
404
class DocHtmlEndTag extends DocNode {
405
  /** Tag name (e.g., "b", "a") */
406
  readonly name: string;
407
}
408

409
/**
410
 * HTML attribute within an HTML tag
411
 */
412
class DocHtmlAttribute extends DocNode {
413
  /** Attribute name */
414
  readonly name: string;
415
  
416
  /** Attribute value (without quotes) */
417
  readonly value: string | undefined;
418
  
419
  /** Spacing after attribute name */
420
  readonly spacingAfterName: string | undefined;
421
  
422
  /** Spacing before equals sign */
423
  readonly spacingBeforeEquals: string | undefined;
424
  
425
  /** Spacing after equals sign */
426
  readonly spacingAfterEquals: string | undefined;
427
}
428
```
429

430
### DocExcerpt
431

432
Special node for token-level content representation.
433

434
```typescript { .api }
435
/**
436
 * Excerpt of tokens representing part of the input
437
 */
438
class DocExcerpt extends DocNode {
439
  /** The type of excerpt */
440
  readonly excerptKind: ExcerptKind;
441
  
442
  /** Token sequence for this excerpt */
443
  readonly content: TokenSequence;
444
}
445

446
enum ExcerptKind {
447
  Content = "Content",
448
  Spacing = "Spacing",
449
  BlockTag = "BlockTag",
450
  InlineTag = "InlineTag"
451
}
452
```
453

454
**Usage Examples:**
455

456
```typescript
457
import { TSDocParser } from "@microsoft/tsdoc";
458

459
const parser = new TSDocParser();
460
const context = parser.parseString(`
461
  /**
462
   * See {@link MyClass.method} for details.
463
   * 
464
   * \`\`\`typescript
465
   * const result = calculate(42);
466
   * \`\`\`
467
   * 
468
   * @example
469
   * Simple usage:
470
   * \`const x = foo();\`
471
   */
472
`);
473

474
// Find inline links
475
const findLinks = (node: DocNode): DocLinkTag[] => {
476
  const links: DocLinkTag[] = [];
477
  if (node instanceof DocLinkTag) {
478
    links.push(node);
479
  }
480
  for (const child of node.getChildNodes()) {
481
    if (child) {
482
      links.push(...findLinks(child));
483
    }
484
  }
485
  return links;
486
};
487

488
const links = findLinks(context.docComment);
489
console.log(`Found ${links.length} links`);
490

491
// Find code blocks
492
const findCodeBlocks = (node: DocNode): DocFencedCode[] => {
493
  const blocks: DocFencedCode[] = [];
494
  if (node instanceof DocFencedCode) {
495
    blocks.push(node);
496
  }
497
  for (const child of node.getChildNodes()) {
498
    if (child) {
499
      blocks.push(...findCodeBlocks(child));
500
    }
501
  }
502
  return blocks;
503
};
504

505
const codeBlocks = findCodeBlocks(context.docComment);
506
codeBlocks.forEach(block => {
507
  console.log(`Code block (${block.language}): ${block.code}`);
508
});
509
```