0
# Configuration Management
1

2
Configuration system for defining TSDoc parsing behavior, tag definitions, validation rules, and custom DocNode types.
3

4
## Capabilities
5

6
### TSDocConfiguration
7

8
Main configuration object that defines TSDoc parsing behavior, tag definitions, and validation rules.
9

10
```typescript { .api }
11
/**
12
 * Main configuration object that defines TSDoc parsing behavior
13
 */
14
class TSDocConfiguration {
15
  constructor();
16
  
17
  /** All registered tag definitions */
18
  readonly tagDefinitions: ReadonlyArray<TSDocTagDefinition>;
19
  
20
  /** Subset of tag definitions that are supported */
21
  readonly supportedTagDefinitions: ReadonlyArray<TSDocTagDefinition>;
22
  
23
  /** Validation configuration for error reporting */
24
  readonly validation: TSDocValidationConfiguration;
25
  
26
  /** Supported HTML element names */
27
  readonly supportedHtmlElements: string[];
28
  
29
  /** Custom DocNode registry */
30
  readonly docNodeManager: DocNodeManager;
31
  
32
  /** All implemented TSDoc message IDs */
33
  readonly allTsdocMessageIds: ReadonlyArray<TSDocMessageId>;
34
  
35
  /** Reset configuration to initial state */
36
  clear(noStandardTags?: boolean): void;
37
  
38
  /** Add a custom tag definition to the configuration */
39
  addTagDefinition(tagDefinition: TSDocTagDefinition): void;
40
  
41
  /** Add multiple tag definitions at once with optional support setting */
42
  addTagDefinitions(tagDefinitions: ReadonlyArray<TSDocTagDefinition>, supported?: boolean): void;
43
  
44
  /** Look up a tag definition by name */
45
  tryGetTagDefinition(tagName: string): TSDocTagDefinition | undefined;
46
  
47
  /** Look up a tag definition by uppercase name for case-insensitive lookup */
48
  tryGetTagDefinitionWithUpperCase(tagNameWithUpperCase: string): TSDocTagDefinition | undefined;
49
  
50
  /** Check if a tag definition is supported */
51
  isTagSupported(tagDefinition: TSDocTagDefinition): boolean;
52
  
53
  /** Enable or disable support for a specific tag */
54
  setSupportForTag(tagDefinition: TSDocTagDefinition, supported: boolean): void;
55
  
56
  /** Enable or disable support for multiple tags */
57
  setSupportForTags(tagDefinitions: ReadonlyArray<TSDocTagDefinition>, supported: boolean): void;
58
  
59
  /** Set supported HTML elements and enable validation */
60
  setSupportedHtmlElements(htmlTags: string[]): void;
61
  
62
  /** Check if an HTML element is supported */
63
  isHtmlElementSupported(htmlTag: string): boolean;
64
  
65
  /** Check if a message ID is implemented by this TSDoc parser release */
66
  isKnownMessageId(messageId: TSDocMessageId | string): boolean;
67
}
68
```
69

70
**Usage Examples:**
71

72
```typescript
73
import { TSDocConfiguration, StandardTags, TSDocMessageId } from "@microsoft/tsdoc";
74

75
// Create a new configuration
76
const configuration = new TSDocConfiguration();
77

78
// Access read-only properties
79
console.log(`Total tags: ${configuration.tagDefinitions.length}`);
80
console.log(`Supported tags: ${configuration.supportedTagDefinitions.length}`);
81

82
// Configure tag support
83
configuration.setSupportForTag(StandardTags.alpha, false);
84
configuration.setSupportForTags([StandardTags.beta, StandardTags.experimental], true);
85

86
// Check if a tag is supported
87
if (configuration.isTagSupported(StandardTags.beta)) {
88
  console.log("Beta tag is supported");
89
}
90

91
// Configure HTML element support
92
configuration.setSupportedHtmlElements(['b', 'i', 'code', 'a', 'br']);
93
console.log(configuration.isHtmlElementSupported('b')); // true
94
console.log(configuration.isHtmlElementSupported('script')); // false
95

96
// Check message ID validity
97
console.log(configuration.isKnownMessageId(TSDocMessageId.UnsupportedTag)); // true
98
console.log(configuration.isKnownMessageId('InvalidMessageId')); // false
99

100
// Access validation settings
101
configuration.validation.reportUnsupportedTags = true;
102
configuration.validation.ignoreUndefinedTags = false;
103

104
// Reset configuration
105
configuration.clear(); // Includes standard tags
106
configuration.clear(true); // Completely empty
107
```
108

109
### TSDocTagDefinition
110

111
Defines the syntax and behavior of a TSDoc tag (e.g., @param, @returns).
112

113
```typescript { .api }
114
/**
115
 * Defines the syntax and behavior of a TSDoc tag
116
 */
117
class TSDocTagDefinition {
118
  constructor(parameters: ITSDocTagDefinitionParameters);
119
  
120
  /** The name of the tag (e.g., "param", "returns") */
121
  readonly tagName: string;
122
  
123
  /** The syntax pattern for this tag */
124
  readonly syntaxKind: TSDocTagSyntaxKind;
125
  
126
  /** Whether multiple instances of this tag are allowed */
127
  readonly allowMultiple: boolean;
128
}
129

130
interface ITSDocTagDefinitionParameters {
131
  /** The name of the tag without the @ symbol */
132
  tagName: string;
133
  
134
  /** The syntax pattern for this tag */
135
  syntaxKind: TSDocTagSyntaxKind;
136
  
137
  /** Whether multiple instances are allowed (default: false) */
138
  allowMultiple?: boolean;
139
}
140

141
/**
142
 * Defines the syntax patterns for TSDoc tags
143
 */
144
enum TSDocTagSyntaxKind {
145
  /** Inline tags like {@link} or {@inheritDoc} */
146
  InlineTag = "InlineTag",
147
  
148
  /** Block tags like @param or @returns */
149
  BlockTag = "BlockTag",
150
  
151
  /** Modifier tags like @public or @beta */
152
  ModifierTag = "ModifierTag"
153
}
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
import { TSDocTagDefinition, TSDocTagSyntaxKind } from "@microsoft/tsdoc";
160

161
// Create a custom block tag
162
const customTag = new TSDocTagDefinition({
163
  tagName: "customNote",
164
  syntaxKind: TSDocTagSyntaxKind.BlockTag,
165
  allowMultiple: true
166
});
167

168
// Create a custom modifier tag
169
const deprecatedTag = new TSDocTagDefinition({
170
  tagName: "deprecated",
171
  syntaxKind: TSDocTagSyntaxKind.ModifierTag,
172
  allowMultiple: false
173
});
174

175
console.log(customTag.tagName); // "customNote"
176
console.log(customTag.allowMultiple); // true
177
```
178

179
### TSDocValidationConfiguration
180

181
Configuration for validation rules and error reporting behavior.
182

183
```typescript { .api }
184
/**
185
 * Configuration for validation rules and error reporting
186
 */
187
class TSDocValidationConfiguration {
188
  constructor();
189
  
190
  /** 
191
   * Set to true to silently ignore unrecognized tags instead of reporting a warning
192
   * @defaultValue false
193
   */
194
  ignoreUndefinedTags: boolean;
195
  
196
  /** 
197
   * Set to true to issue warnings for tags that are not supported by your tool
198
   * @defaultValue false
199
   */
200
  reportUnsupportedTags: boolean;
201
  
202
  /** 
203
   * Set to true to issue warnings for HTML elements not in supportedHtmlElements
204
   * @defaultValue false
205
   */
206
  reportUnsupportedHtmlElements: boolean;
207
}
208
```
209

210
**Usage Examples:**
211

212
```typescript
213
import { TSDocConfiguration, TSDocValidationConfiguration } from "@microsoft/tsdoc";
214

215
const config = new TSDocConfiguration();
216
const validation = config.validation;
217

218
// Configure validation behavior
219
validation.ignoreUndefinedTags = true; // Don't warn about unknown tags
220
validation.reportUnsupportedTags = true; // Warn about unsupported standard tags
221
validation.reportUnsupportedHtmlElements = true; // Warn about unsupported HTML
222

223
// Use with parser
224
const parser = new TSDocParser(config);
225
const context = parser.parseString("/** @unknownTag content */");
226

227
// Check for validation messages
228
if (context.log.messages.length > 0) {
229
  console.log("Validation issues found:");
230
  context.log.messages.forEach(msg => {
231
    console.log(`${msg.messageId}: ${msg.messageText}`);
232
  });
233
}
234
```
235

236
### DocNodeManager
237

238
Registry for DocNode types and their definitions, used for managing custom node types.
239

240
```typescript { .api }
241
/**
242
 * Registry for DocNode types and their definitions
243
 */
244
class DocNodeManager {
245
  constructor();
246
  
247
  /** Register custom DocNode definitions for a package */
248
  registerDocNodes(packageName: string, docNodeDefinitions: ReadonlyArray<IDocNodeDefinition>): void;
249
  
250
  /** Register allowable child relationships between node types */
251
  registerAllowableChildren(parentKind: string, childKinds: ReadonlyArray<string>): void;
252
  
253
  /** Check if a child node type is allowed under a parent node type */
254
  isAllowableChild(parentKind: string, childKind: string): boolean;
255
}
256

257
interface IDocNodeDefinition {
258
  /** The kind identifier for this DocNode type */
259
  docNodeKind: string;
260
  
261
  /** Constructor function for creating instances */
262
  constructor: DocNodeConstructor;
263
}
264

265
type DocNodeConstructor = new (...args: any[]) => DocNode;
266
```
267

268
**Usage Examples:**
269

270
```typescript
271
import { DocNodeManager, DocNode } from "@microsoft/tsdoc";
272

273
// Custom DocNode class
274
class DocCustomTag extends DocNode {
275
  constructor(public readonly content: string) {
276
    super({ docNodeKind: "CustomTag" });
277
  }
278
  
279
  getChildNodes(): ReadonlyArray<DocNode | undefined> {
280
    return [];
281
  }
282
}
283

284
const manager = new DocNodeManager();
285

286
// Register custom node type
287
manager.registerDocNodes("my-package", [
288
  {
289
    docNodeKind: "CustomTag",
290
    constructor: DocCustomTag
291
  }
292
]);
293

294
// Define allowed relationships
295
manager.registerAllowableChildren("DocParagraph", ["CustomTag"]);
296

297
// Check relationships
298
const isAllowed = manager.isAllowableChild("DocParagraph", "CustomTag");
299
console.log(isAllowed); // true
300
```