TSDoc Parser

/**
 * Main parser class that converts TSDoc comment text into an AST
 */
class TSDocParser {
  /** Create a parser with optional configuration */
  constructor(configuration?: TSDocConfiguration);
  
  /** Parse a TSDoc comment from a string */
  parseString(text: string): ParserContext;
  
  /** Parse a TSDoc comment from a TextRange */
  parseRange(textRange: TextRange): ParserContext;
}

import { TSDocParser, TSDocConfiguration } from "@microsoft/tsdoc";

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

// Parse a simple comment
const context = parser.parseString(`
  /**
   * Calculates the sum of two numbers.
   * @param a - The first number
   * @param b - The second number
   * @returns The sum of a and b
   */
`);

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

// Create parser with custom configuration
const config = new TSDocConfiguration();
const customParser = new TSDocParser(config);

/**
 * Context object containing parsing results, AST, and messages
 */
class ParserContext {
  /** Create a new parser context */
  constructor(configuration: TSDocConfiguration, sourceRange: TextRange);
  
  /** The configuration used for parsing */
  readonly configuration: TSDocConfiguration;
  
  /** The range of the comment content (excluding /** and */) */
  readonly commentRange: TextRange;
  
  /** The full range including the comment delimiters */
  readonly sourceRange: TextRange;
  
  /** The parsed comment as an AST */
  readonly docComment: DocComment;
  
  /** Log containing parser messages and errors */
  readonly log: ParserMessageLog;
}

import { TSDocParser } from "@microsoft/tsdoc";

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

// Check for parsing errors
if (context.log.messages.length > 0) {
  console.log("Parsing errors found:");
  context.log.messages.forEach(msg => {
    console.log(`${msg.messageId}: ${msg.messageText}`);
  });
}

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

/**
 * Represents a parser error, warning, or informational message
 */
class ParserMessage {
  constructor(parameters: IParserMessageParameters);
  
  /** Unique identifier for this message type */
  readonly messageId: TSDocMessageId;
  
  /** Human-readable message text */
  readonly messageText: string;
  
  /** Location in source where the message applies */
  readonly textRange: TextRange;
  
  /** Optional token sequence associated with the message */
  readonly tokenSequence: TokenSequence | undefined;
}

interface IParserMessageParameters {
  messageId: TSDocMessageId;
  messageText: string;
  textRange: TextRange;
  tokenSequence?: TokenSequence;
}

/**
 * Collection of parser messages with filtering capabilities
 */
class ParserMessageLog {
  constructor();
  
  /** Add a message to the log */
  addMessage(parserMessage: ParserMessage): void;
  
  /** Add a message for a specific token sequence */
  addMessageForTokenSequence(
    messageId: TSDocMessageId, 
    messageText: string, 
    tokenSequence: TokenSequence, 
    docNode?: DocNode
  ): void;
  
  /** Add a message for a specific text range */
  addMessageForTextRange(
    messageId: TSDocMessageId, 
    messageText: string, 
    textRange: TextRange
  ): void;
  
  /** All messages in the log */
  readonly messages: ReadonlyArray<ParserMessage>;
}

/**
 * Represents a range of characters in source text
 */
class TextRange {
  /** Create a TextRange from an entire string */
  static fromString(buffer: string): TextRange;
  
  /** Create a TextRange from a string with specific bounds */
  static fromStringRange(buffer: string, pos: number, end: number): TextRange;
  
  /** Empty range constant */
  static readonly empty: TextRange;
  
  /** The source text buffer */
  readonly buffer: string;
  
  /** Starting position in the buffer */
  readonly pos: number;
  
  /** Ending position in the buffer */
  readonly end: number;
  
  /** Length of the range */
  readonly length: number;
  
  /** Get line and column location for a specific index */
  getLocation(index: number): ITextLocation;
  
  /** Create a new range from the same buffer */
  getNewRange(pos: number, end: number): TextRange;
  
  /** Check if the range is empty */
  isEmpty(): boolean;
  
  /** Get the text content of this range */
  toString(): string;
  
  /** Get debug representation with delimiters */
  getDebugDump(posDelimiter: string, endDelimiter: string): string;
}

interface ITextLocation {
  /** Line number (1-based) */
  line: number;
  
  /** Column number (1-based) */
  column: number;
}

import { TextRange } from "@microsoft/tsdoc";

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

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

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

// Create from entire string
const fullRange = TextRange.fromString(sourceText);
console.log(fullRange.toString()); // "/** Hello world */"

/**
 * Represents a lexical token in the parsed input
 */
class Token {
  constructor(kind: TokenKind, range: TextRange, line: number, column: number);
  
  /** The type of token */
  readonly kind: TokenKind;
  
  /** Text range for this token */
  readonly range: TextRange;
  
  /** Line number where token appears */
  readonly line: number;
  
  /** Column number where token appears */
  readonly column: number;
}

/**
 * Types of lexical tokens
 */
enum TokenKind {
  AsciiWord = "AsciiWord",
  Other = "Other", 
  Newline = "Newline",
  EndOfInput = "EndOfInput",
  Spacing = "Spacing",
  LeftCurlyBracket = "LeftCurlyBracket",
  RightCurlyBracket = "RightCurlyBracket",
  AtSign = "AtSign",
  Backslash = "Backslash",
  // ... and many more token types
}

/**
 * Immutable sequence of tokens with navigation methods
 */
class TokenSequence {
  constructor(parameters: ITokenSequenceParameters);
  
  /** Create a token sequence from an array of tokens */
  static createFromTokens(tokens: Token[], startIndex: number, endIndex: number): TokenSequence;
  
  /** Get a token at the specified index */
  getToken(index: number): Token;
  
  /** Convert the token sequence to a string */
  toString(): string;
}

interface ITokenSequenceParameters {
  parserContext: ParserContext;
  tokens: ReadonlyArray<Token>;
  startIndex: number;
  endIndex: number;
}

/**
 * Enumeration of all parser message identifiers (60+ values)
 */
enum TSDocMessageId {
  None = "None",
  ReferenceMissingMemberName = "ReferenceMissingMemberName",
  AtSignWithoutTag = "AtSignWithoutTag", 
  UnsupportedTag = "UnsupportedTag",
  InlineTagMissingBraces = "InlineTagMissingBraces",
  TagShouldNotHaveNonePart = "TagShouldNotHaveNonePart",
  InheritDocTagShouldNotHaveOtherContent = "InheritDocTagShouldNotHaveOtherContent",
  UnexpectedEndOfInput = "UnexpectedEndOfInput",
  MissingTag = "MissingTag",
  // ... 50+ more message IDs
}

import { TSDocParser, TSDocMessageId } from "@microsoft/tsdoc";

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

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

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

// Filter messages by type
const errors = context.log.messages.filter(msg => 
  msg.messageId !== TSDocMessageId.None
);