0
# @microsoft/tsdoc
1
2
@microsoft/tsdoc is a reference implementation parser for the TSDoc syntax, which is a proposal to standardize documentation comments used in TypeScript source files. The library enables different tools to extract content from TypeScript documentation comments without conflicts, supporting a standardized syntax similar to JSDoc but specifically designed for TypeScript.
3
4
## Package Information
5
6
- **Package Name**: @microsoft/tsdoc
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @microsoft/tsdoc`
10
11
## Core Imports
12
13
```typescript
14
import { TSDocParser, TSDocConfiguration } from "@microsoft/tsdoc";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { TSDocParser, TSDocConfiguration } = require("@microsoft/tsdoc");
21
```
22
23
## Basic Usage
24
25
```typescript
26
import { TSDocParser, TSDocConfiguration } from "@microsoft/tsdoc";
27
28
// Create configuration and parser
29
const configuration = new TSDocConfiguration();
30
const tsdocParser = new TSDocParser(configuration);
31
32
// Parse a TSDoc comment
33
const parserContext = tsdocParser.parseString(`
34
/**
35
* Calculates the area of a rectangle.
36
* @param width - The width of the rectangle
37
* @param height - The height of the rectangle
38
* @returns The area as a number
39
*/
40
`);
41
42
// Access the parsed AST
43
const docComment = parserContext.docComment;
44
console.log(docComment.summarySection); // Access summary content
45
console.log(parserContext.log.messages); // Check for parsing errors
46
```
47
48
## Architecture
49
50
@microsoft/tsdoc is built around several key components:
51
52
- **Configuration System**: TSDoc configurations, tag definitions, and validation rules that define parsing behavior
53
- **Parser Engine**: Core parser that converts TSDoc comment text into structured AST nodes
54
- **AST Nodes**: 45+ DocNode classes representing all parts of TSDoc comments (text, tags, code blocks, links, etc.)
55
- **Standard Tags**: Comprehensive registry of 75+ standard TSDoc tag definitions organized by standardization level
56
- **Emitters**: Utilities for rendering AST back to TSDoc markup or extracting plain text
57
- **Transforms**: AST manipulation utilities for cleaning and modifying parsed comment trees
58
59
## Capabilities
60
61
### Configuration Management
62
63
Configuration system for defining TSDoc parsing behavior, tag definitions, validation rules, and custom DocNode types.
64
65
```typescript { .api }
66
class TSDocConfiguration {
67
constructor();
68
addTagDefinition(tagDefinition: TSDocTagDefinition): void;
69
tryGetTagDefinition(tagName: string): TSDocTagDefinition | undefined;
70
isTagSupported(tagDefinition: TSDocTagDefinition): boolean;
71
setSupportForTag(tagDefinition: TSDocTagDefinition, supported: boolean): void;
72
}
73
74
class TSDocTagDefinition {
75
constructor(parameters: ITSDocTagDefinitionParameters);
76
readonly tagName: string;
77
readonly syntaxKind: TSDocTagSyntaxKind;
78
readonly allowMultiple: boolean;
79
}
80
81
enum TSDocTagSyntaxKind {
82
InlineTag = "InlineTag",
83
BlockTag = "BlockTag",
84
ModifierTag = "ModifierTag"
85
}
86
```
87
88
[Configuration](./configuration.md)
89
90
### TSDoc Parser
91
92
Core parser engine that converts TSDoc comment text into structured AST nodes with comprehensive error reporting.
93
94
```typescript { .api }
95
class TSDocParser {
96
constructor(configuration?: TSDocConfiguration);
97
parseString(text: string): ParserContext;
98
parseRange(textRange: TextRange): ParserContext;
99
}
100
101
class ParserContext {
102
readonly configuration: TSDocConfiguration;
103
readonly commentRange: TextRange;
104
readonly sourceRange: TextRange;
105
readonly docComment: DocComment;
106
readonly log: ParserMessageLog;
107
}
108
```
109
110
[Parser](./parser.md)
111
112
### AST Node Types
113
114
Comprehensive set of 45+ DocNode classes representing all parts of TSDoc comments including text, tags, code blocks, links, and HTML elements.
115
116
```typescript { .api }
117
abstract class DocNode {
118
readonly kind: string;
119
readonly parent: DocNode | undefined;
120
getChildNodes(): ReadonlyArray<DocNode | undefined>;
121
}
122
123
class DocComment extends DocNode {
124
readonly summarySection: DocSection;
125
readonly remarksBlock: DocBlock | undefined;
126
readonly parameterBlocks: ReadonlyArray<DocParamBlock>;
127
readonly returnsBlock: DocBlock | undefined;
128
readonly modifierTagSet: StandardModifierTagSet;
129
}
130
```
131
132
[AST Nodes](./ast-nodes.md)
133
134
### Standard Tags Registry
135
136
Comprehensive collection of 75+ predefined TSDoc tag definitions organized by standardization level (Core, Extended, Discretionary).
137
138
```typescript { .api }
139
class StandardTags {
140
static readonly allDefinitions: ReadonlyArray<TSDocTagDefinition>;
141
static readonly param: TSDocTagDefinition;
142
static readonly returns: TSDocTagDefinition;
143
static readonly remarks: TSDocTagDefinition;
144
static readonly example: TSDocTagDefinition;
145
static readonly public: TSDocTagDefinition;
146
static readonly beta: TSDocTagDefinition;
147
static readonly alpha: TSDocTagDefinition;
148
}
149
150
enum Standardization {
151
None = "None",
152
Core = "Core",
153
Extended = "Extended",
154
Discretionary = "Discretionary"
155
}
156
```
157
158
[Standard Tags](./standard-tags.md)
159
160
### Content Emitters
161
162
Utilities for rendering DocNode trees back to TSDoc markup or extracting plain text content from parsed comments.
163
164
```typescript { .api }
165
class TSDocEmitter {
166
constructor();
167
renderDocNode(docNode: DocNode): string;
168
renderDocComment(docComment: DocComment): string;
169
}
170
171
class PlainTextEmitter {
172
constructor();
173
renderDocNode(docNode: DocNode): string;
174
renderDocComment(docComment: DocComment): string;
175
}
176
```
177
178
[Emitters](./emitters.md)
179
180
### AST Node Transforms
181
182
Helper utilities for transforming and manipulating DocNode trees after parsing, commonly used for cleaning up comments for rendering.
183
184
```typescript { .api }
185
class DocNodeTransforms {
186
static trimSpacesInParagraphNodes(docParagraph: DocParagraph): ReadonlyArray<DocNode>;
187
}
188
```
189
190
[Transforms](./transforms.md)
191
192
## Common Types
193
194
```typescript { .api }
195
interface ITSDocTagDefinitionParameters {
196
tagName: string;
197
syntaxKind: TSDocTagSyntaxKind;
198
allowMultiple?: boolean;
199
}
200
201
interface IParserMessageParameters {
202
messageId: TSDocMessageId;
203
messageText: string;
204
textRange: TextRange;
205
tokenSequence?: TokenSequence;
206
}
207
208
interface ITextLocation {
209
line: number;
210
column: number;
211
}
212
213
interface IStringBuilder {
214
append(text: string): void;
215
toString(): string;
216
}
217
218
interface IDocNodeDefinition {
219
docNodeKind: string;
220
constructor: DocNodeConstructor;
221
}
222
223
interface ITokenSequenceParameters {
224
parserContext: ParserContext;
225
tokens: ReadonlyArray<Token>;
226
startIndex: number;
227
endIndex: number;
228
}
229
230
type DocNodeConstructor = new (...args: any[]) => DocNode;
231
232
enum TSDocMessageId {
233
None = "None",
234
ReferenceMissingMemberName = "ReferenceMissingMemberName",
235
AtSignWithoutTag = "AtSignWithoutTag",
236
UnsupportedTag = "UnsupportedTag",
237
InlineTagMissingBraces = "InlineTagMissingBraces",
238
TagShouldNotHaveNonePart = "TagShouldNotHaveNonePart",
239
InheritDocTagShouldNotHaveOtherContent = "InheritDocTagShouldNotHaveOtherContent",
240
UnexpectedEndOfInput = "UnexpectedEndOfInput",
241
MissingTag = "MissingTag",
242
// ... 50+ more message IDs for comprehensive error reporting
243
}
244
245
enum TokenKind {
246
AsciiWord = "AsciiWord",
247
Other = "Other",
248
Newline = "Newline",
249
EndOfInput = "EndOfInput",
250
Spacing = "Spacing",
251
LeftCurlyBracket = "LeftCurlyBracket",
252
RightCurlyBracket = "RightCurlyBracket",
253
AtSign = "AtSign",
254
Backslash = "Backslash",
255
// ... additional token types for lexical analysis
256
}
257
258
enum ExcerptKind {
259
Content = "Content",
260
Spacing = "Spacing",
261
BlockTag = "BlockTag",
262
InlineTag = "InlineTag"
263
}
264
```