tessl/npm-microsoft--tsdoc

A parser for the TypeScript doc comment syntax

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

AST Node Transforms

Name: tessl/npm-microsoft--tsdoc
Author: tessl

Helper utilities for transforming and manipulating DocNode trees after parsing. These transforms are commonly used for cleaning up and optimizing parsed comments for rendering.

Capabilities

DocNodeTransforms

Static class providing utility functions for transforming DocNode trees.

/**
 * Helper functions that transform DocNode trees
 */
class DocNodeTransforms {
  /** 
   * Collapses extra spacing characters from plain text nodes in paragraphs
   * @param docParagraph - A DocParagraph containing nodes to be transformed
   * @returns The transformed child nodes
   */
  static trimSpacesInParagraphNodes(docParagraph: DocParagraph): ReadonlyArray<DocNode>;
}

Usage Examples:

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

const parser = new TSDocParser();
const context = parser.parseString(`
  /**
   * This   has   extra    spaces   and
   * line breaks    with   more   spacing.
   */
`);

// Find paragraph nodes and apply transform
const findParagraphs = (node: DocNode): DocParagraph[] => {
  const paragraphs: DocParagraph[] = [];
  if (node instanceof DocParagraph) {
    paragraphs.push(node);
  }
  for (const child of node.getChildNodes()) {
    if (child) {
      paragraphs.push(...findParagraphs(child));
    }
  }
  return paragraphs;
};

const paragraphs = findParagraphs(context.docComment);
paragraphs.forEach(paragraph => {
  // Apply spacing transformation
  const transformedNodes = DocNodeTransforms.trimSpacesInParagraphNodes(paragraph);
  console.log(`Original nodes: ${paragraph.getChildNodes().length}`);
  console.log(`Transformed nodes: ${transformedNodes.length}`);
});

Transform Use Cases

The spacing transform is particularly useful for:

HTML Rendering: Where multiple spaces are equivalent to a single space
Markdown Output: Where spaces can be misinterpreted as indented code blocks
Clean Text Extraction: For generating readable plain text from comments
Optimization: Reducing redundant whitespace nodes in the AST

Before Transform:

nodes: [
  { kind: PlainText, text: "   Here   are some   " },
  { kind: SoftBreak },
  { kind: PlainText, text: "   words" },
  { kind: SoftBreak },
  { kind: InlineTag, text: "{@inheritDoc}" },
  { kind: PlainText, text: "to process." },
  { kind: PlainText, text: "  " }
]

After Transform:

nodes: [
  { kind: PlainText, text: "Here are some " },
  { kind: PlainText, text: "words " },
  { kind: InlineTag, text: "{@inheritDoc}" },
  { kind: PlainText, text: "to process." }
]

Note that "words " is not merged with the preceding node because DocPlainText excerpts cannot span multiple lines.