0
# TSDoc Parser
1

2
Core parser engine that converts TSDoc comment text into structured AST nodes with comprehensive error reporting and token-level analysis.
3

4
## Capabilities
5

6
### TSDocParser
7

8
Main parser class that converts TSDoc comment text into an AST.
9

10
```typescript { .api }
11
/**
12
 * Main parser class that converts TSDoc comment text into an AST
13
 */
14
class TSDocParser {
15
  /** Create a parser with optional configuration */
16
  constructor(configuration?: TSDocConfiguration);
17
  
18
  /** Parse a TSDoc comment from a string */
19
  parseString(text: string): ParserContext;
20
  
21
  /** Parse a TSDoc comment from a TextRange */
22
  parseRange(textRange: TextRange): ParserContext;
23
}
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
import { TSDocParser, TSDocConfiguration } from "@microsoft/tsdoc";
30

31
// Create parser with default configuration
32
const parser = new TSDocParser();
33

34
// Parse a simple comment
35
const context = parser.parseString(`
36
  /**
37
   * Calculates the sum of two numbers.
38
   * @param a - The first number
39
   * @param b - The second number
40
   * @returns The sum of a and b
41
   */
42
`);
43

44
// Access parsed content
45
console.log(context.docComment.summarySection);
46
console.log(context.log.messages.length); // Check for errors
47

48
// Create parser with custom configuration
49
const config = new TSDocConfiguration();
50
const customParser = new TSDocParser(config);
51
```
52

53
### ParserContext
54

55
Context object containing parsing results, AST, and messages.
56

57
```typescript { .api }
58
/**
59
 * Context object containing parsing results, AST, and messages
60
 */
61
class ParserContext {
62
  /** Create a new parser context */
63
  constructor(configuration: TSDocConfiguration, sourceRange: TextRange);
64
  
65
  /** The configuration used for parsing */
66
  readonly configuration: TSDocConfiguration;
67
  
68
  /** The range of the comment content (excluding /** and */) */
69
  readonly commentRange: TextRange;
70
  
71
  /** The full range including the comment delimiters */
72
  readonly sourceRange: TextRange;
73
  
74
  /** The parsed comment as an AST */
75
  readonly docComment: DocComment;
76
  
77
  /** Log containing parser messages and errors */
78
  readonly log: ParserMessageLog;
79
}
80
```
81

82
**Usage Examples:**
83

84
```typescript
85
import { TSDocParser } from "@microsoft/tsdoc";
86

87
const parser = new TSDocParser();
88
const context = parser.parseString("/** @param name - User name */");
89

90
// Check for parsing errors
91
if (context.log.messages.length > 0) {
92
  console.log("Parsing errors found:");
93
  context.log.messages.forEach(msg => {
94
    console.log(`${msg.messageId}: ${msg.messageText}`);
95
  });
96
}
97

98
// Access the parsed comment
99
const paramBlocks = context.docComment.parameterBlocks;
100
if (paramBlocks.length > 0) {
101
  console.log(`Parameter: ${paramBlocks[0].parameterName}`);
102
}
103
```
104

105
### ParserMessage
106

107
Represents a parser error, warning, or informational message.
108

109
```typescript { .api }
110
/**
111
 * Represents a parser error, warning, or informational message
112
 */
113
class ParserMessage {
114
  constructor(parameters: IParserMessageParameters);
115
  
116
  /** Unique identifier for this message type */
117
  readonly messageId: TSDocMessageId;
118
  
119
  /** Human-readable message text */
120
  readonly messageText: string;
121
  
122
  /** Location in source where the message applies */
123
  readonly textRange: TextRange;
124
  
125
  /** Optional token sequence associated with the message */
126
  readonly tokenSequence: TokenSequence | undefined;
127
}
128

129
interface IParserMessageParameters {
130
  messageId: TSDocMessageId;
131
  messageText: string;
132
  textRange: TextRange;
133
  tokenSequence?: TokenSequence;
134
}
135
```
136

137
### ParserMessageLog
138

139
Collection of parser messages with filtering capabilities.
140

141
```typescript { .api }
142
/**
143
 * Collection of parser messages with filtering capabilities
144
 */
145
class ParserMessageLog {
146
  constructor();
147
  
148
  /** Add a message to the log */
149
  addMessage(parserMessage: ParserMessage): void;
150
  
151
  /** Add a message for a specific token sequence */
152
  addMessageForTokenSequence(
153
    messageId: TSDocMessageId, 
154
    messageText: string, 
155
    tokenSequence: TokenSequence, 
156
    docNode?: DocNode
157
  ): void;
158
  
159
  /** Add a message for a specific text range */
160
  addMessageForTextRange(
161
    messageId: TSDocMessageId, 
162
    messageText: string, 
163
    textRange: TextRange
164
  ): void;
165
  
166
  /** All messages in the log */
167
  readonly messages: ReadonlyArray<ParserMessage>;
168
}
169
```
170

171
### TextRange
172

173
Represents a range of characters in source text with location tracking.
174

175
```typescript { .api }
176
/**
177
 * Represents a range of characters in source text
178
 */
179
class TextRange {
180
  /** Create a TextRange from an entire string */
181
  static fromString(buffer: string): TextRange;
182
  
183
  /** Create a TextRange from a string with specific bounds */
184
  static fromStringRange(buffer: string, pos: number, end: number): TextRange;
185
  
186
  /** Empty range constant */
187
  static readonly empty: TextRange;
188
  
189
  /** The source text buffer */
190
  readonly buffer: string;
191
  
192
  /** Starting position in the buffer */
193
  readonly pos: number;
194
  
195
  /** Ending position in the buffer */
196
  readonly end: number;
197
  
198
  /** Length of the range */
199
  readonly length: number;
200
  
201
  /** Get line and column location for a specific index */
202
  getLocation(index: number): ITextLocation;
203
  
204
  /** Create a new range from the same buffer */
205
  getNewRange(pos: number, end: number): TextRange;
206
  
207
  /** Check if the range is empty */
208
  isEmpty(): boolean;
209
  
210
  /** Get the text content of this range */
211
  toString(): string;
212
  
213
  /** Get debug representation with delimiters */
214
  getDebugDump(posDelimiter: string, endDelimiter: string): string;
215
}
216

217
interface ITextLocation {
218
  /** Line number (1-based) */
219
  line: number;
220
  
221
  /** Column number (1-based) */
222
  column: number;
223
}
224
```
225

226
**Usage Examples:**
227

228
```typescript
229
import { TextRange } from "@microsoft/tsdoc";
230

231
const sourceText = "/** Hello world */";
232
const range = TextRange.fromStringRange(sourceText, 4, 15); // "Hello world"
233

234
console.log(range.toString()); // "Hello world"
235
console.log(range.isEmpty()); // false
236
console.log(range.length); // 11
237

238
const location = range.getLocation(4);
239
console.log(`Line ${location.line}, Column ${location.column}`);
240

241
// Create from entire string
242
const fullRange = TextRange.fromString(sourceText);
243
console.log(fullRange.toString()); // "/** Hello world */"
244
```
245

246
### Token and TokenSequence
247

248
Low-level lexical analysis components for token-level parsing.
249

250
```typescript { .api }
251
/**
252
 * Represents a lexical token in the parsed input
253
 */
254
class Token {
255
  constructor(kind: TokenKind, range: TextRange, line: number, column: number);
256
  
257
  /** The type of token */
258
  readonly kind: TokenKind;
259
  
260
  /** Text range for this token */
261
  readonly range: TextRange;
262
  
263
  /** Line number where token appears */
264
  readonly line: number;
265
  
266
  /** Column number where token appears */
267
  readonly column: number;
268
}
269

270
/**
271
 * Types of lexical tokens
272
 */
273
enum TokenKind {
274
  AsciiWord = "AsciiWord",
275
  Other = "Other", 
276
  Newline = "Newline",
277
  EndOfInput = "EndOfInput",
278
  Spacing = "Spacing",
279
  LeftCurlyBracket = "LeftCurlyBracket",
280
  RightCurlyBracket = "RightCurlyBracket",
281
  AtSign = "AtSign",
282
  Backslash = "Backslash",
283
  // ... and many more token types
284
}
285

286
/**
287
 * Immutable sequence of tokens with navigation methods
288
 */
289
class TokenSequence {
290
  constructor(parameters: ITokenSequenceParameters);
291
  
292
  /** Create a token sequence from an array of tokens */
293
  static createFromTokens(tokens: Token[], startIndex: number, endIndex: number): TokenSequence;
294
  
295
  /** Get a token at the specified index */
296
  getToken(index: number): Token;
297
  
298
  /** Convert the token sequence to a string */
299
  toString(): string;
300
}
301

302
interface ITokenSequenceParameters {
303
  parserContext: ParserContext;
304
  tokens: ReadonlyArray<Token>;
305
  startIndex: number;
306
  endIndex: number;
307
}
308
```
309

310
### TSDocMessageId
311

312
Enumeration of all parser message identifiers for error reporting.
313

314
```typescript { .api }
315
/**
316
 * Enumeration of all parser message identifiers (60+ values)
317
 */
318
enum TSDocMessageId {
319
  None = "None",
320
  ReferenceMissingMemberName = "ReferenceMissingMemberName",
321
  AtSignWithoutTag = "AtSignWithoutTag", 
322
  UnsupportedTag = "UnsupportedTag",
323
  InlineTagMissingBraces = "InlineTagMissingBraces",
324
  TagShouldNotHaveNonePart = "TagShouldNotHaveNonePart",
325
  InheritDocTagShouldNotHaveOtherContent = "InheritDocTagShouldNotHaveOtherContent",
326
  UnexpectedEndOfInput = "UnexpectedEndOfInput",
327
  MissingTag = "MissingTag",
328
  // ... 50+ more message IDs
329
}
330
```
331

332
**Usage Examples:**
333

334
```typescript
335
import { TSDocParser, TSDocMessageId } from "@microsoft/tsdoc";
336

337
const parser = new TSDocParser();
338
const context = parser.parseString("/** @unknownTag content */");
339

340
// Check for specific error types
341
const hasUnsupportedTag = context.log.messages.some(
342
  msg => msg.messageId === TSDocMessageId.UnsupportedTag
343
);
344

345
if (hasUnsupportedTag) {
346
  console.log("Found unsupported tag in comment");
347
}
348

349
// Filter messages by type
350
const errors = context.log.messages.filter(msg => 
351
  msg.messageId !== TSDocMessageId.None
352
);
353
```