0
# Custom Doc Nodes
1

2
Enhanced TSDoc node system that extends the standard TSDoc markup with specialized elements for rich documentation. These custom nodes enable advanced formatting and structure in generated documentation.
3

4
## Capabilities
5

6
### CustomDocNodeKind
7

8
Enumeration defining all available custom doc node types.
9

10
```typescript { .api }
11
enum CustomDocNodeKind {
12
  EmphasisSpan = 'EmphasisSpan',
13
  Heading = 'Heading', 
14
  NoteBox = 'NoteBox',
15
  Table = 'Table',
16
  TableCell = 'TableCell',
17
  TableRow = 'TableRow'
18
}
19
```
20

21
### CustomDocNodes
22

23
TSDoc configuration class that registers custom node definitions for parsing and rendering.
24

25
```typescript { .api }
26
class CustomDocNodes {
27
  /**
28
   * Gets the TSDoc configuration with custom nodes registered
29
   * @returns Configured TSDocConfiguration instance
30
   */
31
  static get configuration(): TSDocConfiguration;
32
}
33
```
34

35
**Usage Example:**
36

37
```typescript
38
import { CustomDocNodes } from "@microsoft/api-documenter/lib/nodes/CustomDocNodes";
39
import { TSDocParser } from "@microsoft/tsdoc";
40

41
// Use custom nodes configuration
42
const parser = new TSDocParser(CustomDocNodes.configuration);
43
```
44

45
### DocHeading
46

47
Custom heading element with configurable title and level for structured documentation.
48

49
```typescript { .api }
50
class DocHeading extends DocNode {
51
  /**
52
   * The heading text content
53
   */
54
  readonly title: string;
55
  
56
  /**
57
   * The heading level (1-5, where 1 is largest)
58
   */
59
  readonly level: number;
60
  
61
  /**
62
   * Creates a new DocHeading instance
63
   * @param parameters - Heading configuration parameters
64
   */
65
  constructor(parameters: IDocHeadingParameters);
66
}
67

68
interface IDocHeadingParameters {
69
  /**
70
   * Configuration for the DocNode base class
71
   */
72
  configuration: TSDocConfiguration;
73
  
74
  /**
75
   * The heading text content
76
   */
77
  title: string;
78
  
79
  /**
80
   * The heading level (1-5, where 1 is largest)
81
   */
82
  level: number;
83
}
84
```
85

86
**Usage Example:**
87

88
```typescript
89
const heading = new DocHeading({
90
  configuration: CustomDocNodes.configuration,
91
  title: "API Reference",
92
  level: 2
93
});
94
```
95

96
### DocNoteBox  
97

98
Custom callout container for highlighting important information, warnings, or tips in documentation.
99

100
```typescript { .api }
101
class DocNoteBox extends DocNode {
102
  /**
103
   * Creates a new DocNoteBox instance
104
   * @param parameters - Note box configuration parameters
105
   */
106
  constructor(parameters: IDocNoteBoxParameters);
107
}
108

109
interface IDocNoteBoxParameters {
110
  /**
111
   * Configuration for the DocNode base class
112
   */
113
  configuration: TSDocConfiguration;
114
  
115
  /**
116
   * The content inside the note box
117
   */
118
  content: DocNode[];
119
}
120
```
121

122
**Usage Example:**
123

124
```typescript
125
const noteBox = new DocNoteBox({
126
  configuration: CustomDocNodes.configuration,
127
  content: [
128
    new DocPlainText({
129
      configuration: CustomDocNodes.configuration,
130
      text: "Important: This API is experimental and may change."
131
    })
132
  ]
133
});
134
```
135

136
### DocTable
137

138
Custom table container for structured tabular data in documentation.
139

140
```typescript { .api }
141
class DocTable extends DocNode {
142
  /**
143
   * Creates a new DocTable instance
144
   * @param parameters - Table configuration parameters  
145
   */
146
  constructor(parameters: IDocTableParameters);
147
  
148
  /**
149
   * Creates a new table row and adds it to the table
150
   * @returns New DocTableRow instance
151
   */
152
  createAndAddRow(): DocTableRow;
153
}
154

155
interface IDocTableParameters {
156
  /**
157
   * Configuration for the DocNode base class
158
   */
159
  configuration: TSDocConfiguration;
160
  
161
  /**
162
   * Optional table header row
163
   */
164
  headerRow?: DocTableRow;
165
  
166
  /**
167
   * Array of table rows
168
   */
169
  rows?: DocTableRow[];
170
}
171
```
172

173
### DocTableRow
174

175
Table row container that holds table cells.
176

177
```typescript { .api }
178
class DocTableRow extends DocNode {
179
  /**
180
   * Creates a new DocTableRow instance
181
   * @param parameters - Table row configuration parameters
182
   */
183
  constructor(parameters: IDocTableRowParameters);
184
  
185
  /**
186
   * Creates a new table cell and adds it to the row
187
   * @returns New DocTableCell instance
188
   */
189
  createAndAddCell(): DocTableCell;
190
}
191

192
interface IDocTableRowParameters {
193
  /**
194
   * Configuration for the DocNode base class  
195
   */
196
  configuration: TSDocConfiguration;
197
  
198
  /**
199
   * Array of table cells in this row
200
   */
201
  cells?: DocTableCell[];
202
}
203
```
204

205
### DocTableCell
206

207
Individual table cell containing content.
208

209
```typescript { .api }
210
class DocTableCell extends DocNode {
211
  /**
212
   * Creates a new DocTableCell instance
213
   * @param parameters - Table cell configuration parameters
214
   */
215
  constructor(parameters: IDocTableCellParameters);
216
}
217

218
interface IDocTableCellParameters {
219
  /**
220
   * Configuration for the DocNode base class
221
   */
222
  configuration: TSDocConfiguration;
223
  
224
  /**
225
   * Content inside the table cell
226
   */
227
  content: DocNode[];
228
}
229
```
230

231
**Table Usage Example:**
232

233
```typescript
234
import { DocTable, DocTableRow, DocTableCell, DocPlainText } from "@microsoft/api-documenter";
235

236
// Create table
237
const table = new DocTable({
238
  configuration: CustomDocNodes.configuration
239
});
240

241
// Add header row
242
const headerRow = table.createAndAddRow();
243
const nameHeader = headerRow.createAndAddCell();
244
nameHeader.appendNode(new DocPlainText({
245
  configuration: CustomDocNodes.configuration,
246
  text: "Parameter"
247
}));
248

249
const typeHeader = headerRow.createAndAddCell();
250
typeHeader.appendNode(new DocPlainText({
251
  configuration: CustomDocNodes.configuration,
252
  text: "Type"
253
}));
254

255
// Add data row
256
const dataRow = table.createAndAddRow();
257
const nameCell = dataRow.createAndAddCell();
258
nameCell.appendNode(new DocPlainText({
259
  configuration: CustomDocNodes.configuration,
260
  text: "options"
261
}));
262

263
const typeCell = dataRow.createAndAddCell();
264
typeCell.appendNode(new DocPlainText({
265
  configuration: CustomDocNodes.configuration,
266
  text: "ConfigOptions"
267
}));
268
```
269

270
### DocEmphasisSpan
271

272
Custom emphasis element for inline text styling and highlighting.
273

274
```typescript { .api }
275
class DocEmphasisSpan extends DocNode {
276
  /**
277
   * Creates a new DocEmphasisSpan instance
278
   * @param parameters - Emphasis span configuration parameters
279
   */
280
  constructor(parameters: IDocEmphasisSpanParameters);
281
}
282

283
interface IDocEmphasisSpanParameters {
284
  /**
285
   * Configuration for the DocNode base class
286
   */
287
  configuration: TSDocConfiguration;
288
  
289
  /**
290
   * Whether the emphasis should be bold formatting
291
   */
292
  bold?: boolean;
293
  
294
  /**
295
   * Whether the emphasis should be italic formatting  
296
   */
297
  italic?: boolean;
298
  
299
  /**
300
   * Content inside the emphasis span
301
   */
302
  content: DocNode[];
303
}
304
```
305

306
**Usage Example:**
307

308
```typescript
309
const emphasis = new DocEmphasisSpan({
310
  configuration: CustomDocNodes.configuration,
311
  bold: true,
312
  italic: false,
313
  content: [
314
    new DocPlainText({
315
      configuration: CustomDocNodes.configuration,
316
      text: "Important Note"
317
    })
318
  ]
319
});
320
```
321

322
## Advanced Usage
323

324
### Custom Markdown Emitter Integration
325

326
Custom doc nodes integrate with the markdown emitter system for proper rendering:
327

328
```typescript
329
import { CustomMarkdownEmitter } from "@microsoft/api-documenter/lib/markdown/CustomMarkdownEmitter";
330
import { DocHeading, DocTable } from "@microsoft/api-documenter";
331

332
class EnhancedMarkdownEmitter extends CustomMarkdownEmitter {
333
  protected writeHeading(docHeading: DocHeading): void {
334
    // Custom heading rendering
335
    const level = Math.min(docHeading.level, 6);
336
    this.writeNewline();
337
    this.writePlainText('#'.repeat(level) + ' ' + docHeading.title);
338
    this.writeNewline();
339
  }
340
  
341
  protected writeTable(docTable: DocTable): void {
342
    // Custom table rendering with enhanced formatting
343
    this.writeNewline();
344
    this.writePlainText('| Column 1 | Column 2 |');
345
    this.writeNewline();
346
    this.writePlainText('|----------|----------|');
347
    // ... render table rows
348
    this.writeNewline();
349
  }
350
}
351
```
352

353
### TSDoc Integration
354

355
Custom nodes work seamlessly with TSDoc parsing and can be used in API documentation comments:
356

357
```typescript
358
/**
359
 * Process configuration options for the API.
360
 * 
361
 * @customHeading Configuration Structure
362
 * 
363
 * @customTable
364
 * | Property | Type | Description |
365
 * |----------|------|-------------|
366
 * | timeout  | number | Request timeout in ms |
367
 * | retries  | number | Maximum retry attempts |
368
 * 
369
 * @customNote
370
 * This API is available in version 2.0 and later.
371
 * 
372
 * @param options - Configuration object
373
 * @returns Promise resolving to processed result
374
 */
375
function processConfig(options: ConfigOptions): Promise<ProcessResult>;
376
```
377

378
## Error Handling
379

380
Custom doc nodes provide validation and error handling:
381

382
- **Invalid Parameters**: Clear error messages for missing or invalid node parameters
383
- **Configuration Errors**: Validation of TSDoc configuration compatibility  
384
- **Nesting Violations**: Prevention of invalid node nesting (e.g., tables inside emphasis spans)
385
- **Rendering Failures**: Graceful fallbacks when custom nodes cannot be rendered