How to use the @microsoft/tsdoc.TSDocParser function in @microsoft/tsdoc

export function simpleDemo(): void {
  console.log(colors.yellow('*** TSDoc API demo: Simple Scenario ***') + os.EOL);

  const inputFilename: string = path.resolve(path.join(__dirname, '..', 'assets', 'simple-input.ts'));
  console.log('Reading assets/simple-input.ts...');

  const inputBuffer: string = fs.readFileSync(inputFilename).toString();

  // NOTE: Optionally, can provide a TSDocParserConfiguration here
  const tsdocParser: TSDocParser = new TSDocParser();
  const parserContext: ParserContext = tsdocParser.parseString(inputBuffer);

  console.log(os.EOL + colors.green('Input Buffer:') + os.EOL);
  console.log(colors.gray('<<<<<<'));
  console.log(inputBuffer);
  console.log(colors.gray('>>>>>>'));

  console.log(os.EOL + colors.green('Extracted Lines:') + os.EOL);
  console.log(JSON.stringify(parserContext.lines.map(x => x.toString()), undefined, '  '));

  console.log(os.EOL + colors.green('Parser Log Messages:') + os.EOL);

  if (parserContext.log.messages.length === 0) {
    console.log('No errors or warnings.');
  } else {
    for (const message of parserContext.log.messages) {

import * as colors from 'colors';
import * as fs from 'fs';
import * as path from 'path';
import * as os from 'os';
import { TSDocParser, ParserContext, DocComment } from '@microsoft/tsdoc';
import { Formatter } from './Formatter';

console.log(colors.cyan('*** TSDoc API demo ***') + os.EOL);

const inputFilename: string = path.resolve(path.join(__dirname, '..', 'assets', 'demo-input.ts'));
console.log('Reading assets/demo-input.ts...');

const inputBuffer: string = fs.readFileSync(inputFilename).toString();

// NOTE: Optionally, can provide a TSDocParserConfiguration here
const tsdocParser: TSDocParser = new TSDocParser();
const parserContext: ParserContext = tsdocParser.parseString(inputBuffer);

console.log(os.EOL + colors.green('Input Buffer:') + os.EOL);
console.log(colors.gray('<<<<<<'));
console.log(inputBuffer);
console.log(colors.gray('>>>>>>'));

console.log(os.EOL + colors.green('Extracted Lines:') + os.EOL);
console.log(JSON.stringify(parserContext.lines.map(x => x.toString()), undefined, '  '));

console.log(os.EOL + colors.green('Parser Log Messages:') + os.EOL);

if (parserContext.log.messages.length === 0) {
  console.log('No errors or warnings.');
} else {
  for (const message of parserContext.log.messages.map(x => x.toString())) {

// NOTE: Defining this causes @customModifier to be removed from its section,
  // and added to the docComment.modifierTagSet
  const customModifierDefinition: tsdoc.TSDocTagDefinition = new tsdoc.TSDocTagDefinition({
    tagName: '@customModifier',
    syntaxKind: tsdoc.TSDocTagSyntaxKind.ModifierTag
  });

  customConfiguration.addTagDefinitions([
    customInlineDefinition,
    customBlockDefinition,
    customModifierDefinition
  ]);

  console.log(os.EOL + 'Invoking TSDocParser with custom configuration...' + os.EOL);
  const tsdocParser: tsdoc.TSDocParser = new tsdoc.TSDocParser(customConfiguration);
  const parserContext: tsdoc.ParserContext = tsdocParser.parseRange(foundComment.textRange);
  const docComment: tsdoc.DocComment = parserContext.docComment;

  console.log(os.EOL + colors.green('Parser Log Messages:') + os.EOL);

  if (parserContext.log.messages.length === 0) {
    console.log('No errors or warnings.');
  } else {
    const sourceFile: ts.SourceFile = foundComment.compilerNode.getSourceFile();
    for (const message of parserContext.log.messages) {
      // Since we have the compiler's analysis, use it to calculate the line/column information,
      // since this is currently faster than TSDoc's TextRange.getLocation() lookup.
      const location: ts.LineAndCharacter = sourceFile.getLineAndCharacterOfPosition(message.textRange.pos);
      const formattedMessage: string = `${sourceFile.fileName}(${location.line + 1},${location.character + 1}):`
        + ` [TSDoc] ${message}`;
      console.log(formattedMessage);

public static onDeserializeInto(options: Partial, context: DeserializerContext,
    jsonObject: IApiItemJson): void {

    super.onDeserializeInto(options,  context, jsonObject);

    const documentedJson: IApiDocumentedItemJson = jsonObject as IApiDocumentedItemJson;

    if (documentedJson.docComment) {
      const tsdocParser: tsdoc.TSDocParser = new tsdoc.TSDocParser(AedocDefinitions.tsdocConfiguration);

      // NOTE: For now, we ignore TSDoc errors found in a serialized .api.json file.
      // Normally these errors would have already been reported by API Extractor during analysis.
      // However, they could also arise if the JSON file was edited manually, or if the file was saved
      // using a different release of the software that used an incompatible syntax.
      const parserContext: tsdoc.ParserContext = tsdocParser.parseString(documentedJson.docComment);

      options.docComment = parserContext.docComment;
    }
  }

tsdocConfiguration.addTagDefinitions([
          new TSDocTagDefinition({
            tagName: '@betaDocumentation',
            syntaxKind: TSDocTagSyntaxKind.ModifierTag
          }),
          new TSDocTagDefinition({
            tagName: '@internalRemarks',
            syntaxKind: TSDocTagSyntaxKind.BlockTag
          }),
          new TSDocTagDefinition({
            tagName: '@preapproved',
            syntaxKind: TSDocTagSyntaxKind.ModifierTag
          })
        ], true);

        const tsdocParser: TSDocParser = new TSDocParser(tsdocConfiguration);

        const sourceCode: eslint.SourceCode = context.getSourceCode();
        const checkCommentBlocks: (node: ESTree.Node) => void = function (node: ESTree.Node) {
          for (const comment of sourceCode.getAllComments()) {
            if (comment.type !== "Block") {
              continue;
            }
            if (!comment.range) {
              continue;
            }

            const textRange: TextRange = TextRange.fromStringRange(sourceCode.text, comment.range[0], comment.range[1]);

            // Smallest comment is "/***/"
            if (textRange.length < 5) {
              continue;

private _parseDocs(inputTextRange: TextRange): void {
    const tsdocParser: TSDocParser = new TSDocParser(AedocDefinitions.parserConfiguration);
    this._parserContext = tsdocParser.parseRange(inputTextRange);
    this._docComment = this._parserContext.docComment;

    for (const message of this._parserContext.log.messages) {
      this.reportError(message.unformattedText, message.textRange.pos);
    }

    this._parseModifierTags();
    this._parseSections();
  }

function parseTSDoc(foundComment: IFoundComment): ConfigComment {
  const customConfiguration: tsdoc.TSDocConfiguration = new tsdoc.TSDocConfiguration();

  customConfiguration.addTagDefinitions([nameDefinition, typeDefinition, descriptionDefinition, warningDefinition, defaultDefinition]);

  const tsdocParser: tsdoc.TSDocParser = new tsdoc.TSDocParser(customConfiguration);
  const parserContext: tsdoc.ParserContext = tsdocParser.parseRange(foundComment.textRange);
  const docComment: tsdoc.DocComment = parserContext.docComment;

  return {
    name: getTagValue(nameDefinition, docComment).trim(),
    type: (getTagValue(typeDefinition, docComment) || '').trim(),
    description: getTagValue(descriptionDefinition, docComment, false) || '',
    defaultValue: (getTagValue(defaultDefinition, docComment) || '').trim(),
    warning: getTagValue(warningDefinition, docComment, false) || '',
    examples: extractExamples(docComment),
  };
}

private _reparseTimer_onTick(): void {
    if (!this._reparseNeeded) {
      return;
    }
    this._reparseNeeded = false;
    try {
      const inputText: string = this.state.inputText;
      const configuration: tsdoc.TSDocConfiguration = new tsdoc.TSDocConfiguration();
      configuration.addTagDefinition(new tsdoc.TSDocTagDefinition({
        tagName: '@sampleCustomBlockTag',
        syntaxKind: tsdoc.TSDocTagSyntaxKind.BlockTag
      }));
      const tsdocParser: tsdoc.TSDocParser = new tsdoc.TSDocParser(configuration);
      const parserContext: tsdoc.ParserContext = tsdocParser.parseString(inputText);

      this.setState({
        parserContext: parserContext,
        parserFailureText: undefined
      });
    } catch (error) {
      this.setState({
        parserContext: undefined,
        parserFailureText: 'Unhandled exception: ' + error.message
      });
    }
  }
}