tessl/npm-tsickle

Transpile TypeScript code to JavaScript with Closure annotations.

—

Pending

Overview

Eval results

Files

JSDoc Processing

Name: tessl/npm-tsickle
Author: tessl

Comprehensive JSDoc parsing, transformation, and generation system for maintaining Closure Compiler compatibility while preserving and enhancing documentation throughout the transformation process.

Capabilities

JSDoc Parsing

Functions for parsing JSDoc comments from TypeScript source code.

/**
 * Parses JSDoc from synthesized comment
 */
function parse(comment: ts.SynthesizedComment): ParsedJSDocComment | null;

/**
 * Parses JSDoc from comment text
 */
function parseContents(commentText: string): ParsedJSDocComment | null;

interface ParsedJSDocComment {
  tags: Tag[];
  warnings?: string[];
}

interface Tag {
  tagName: string;
  parameterName?: string;
  type?: string;
  optional?: boolean;
  restParam?: boolean;
}

Usage Example:

import { parse, parseContents } from "tsickle";

// Parse from comment range
const commentRange = { pos: 0, end: 50, kind: ts.SyntaxKind.MultiLineCommentTrivia };
const parsed = parse(commentRange);

// Parse from text directly
const jsDocText = "/** @param {string} name - The user name */";
const parsed2 = parseContents(jsDocText);

console.log(parsed2.tags); // [{ tagName: 'param', type: 'string', parameterName: 'name' }]

JSDoc Generation

Functions for converting parsed tags back to JSDoc strings and comments.

/**
 * Serializes tags to string
 */
function toString(tags: Tag[], escapeExtraTags?: boolean): string;

/**
 * Converts tags to synthesized comment
 */
function toSynthesizedComment(tags: Tag[], escapeExtraTags?: boolean): ts.SynthesizedComment;

/**
 * Merges multiple tag arrays
 */
function merge(tagLists: Tag[][]): Tag[];

Usage Example:

import { toString, toSynthesizedComment, merge } from "tsickle";

const tags: Tag[] = [
  { tagName: 'param', type: 'string', parameterName: 'name' },
  { tagName: 'return', type: 'boolean' }
];

// Convert to string
const jsDocString = toString(tags);
// Result: "/**\n * @param {string} name\n * @return {boolean}\n */"

// Convert to synthesized comment for AST
const comment = toSynthesizedComment(tags);

// Merge multiple tag sets
const moreTags: Tag[] = [{ tagName: 'deprecated' }];
const merged = merge([tags, moreTags]);

Comment Synthesis and Management

Functions for managing comments in the AST during transformation.

/**
 * Creates synthetic leading comments for node
 */
function synthesizeLeadingComments(
  node: ts.Node,
  comments: SynthesizedCommentWithOriginal[]
): ts.Node;

/**
 * Gets leading comment ranges including synthesized
 */
function getLeadingCommentRangesSynthesized(
  node: ts.Node
): SynthesizedCommentWithOriginal[] | undefined;

/**
 * Recursively suppresses leading comments
 */
function suppressLeadingCommentsRecursively(node: ts.Node): void;

interface SynthesizedCommentWithOriginal extends ts.SynthesizedComment {
  originalRange?: ts.CommentRange;
}

Text Processing Utilities

Utility functions for processing comment text and formatting.

/**
 * Normalizes line endings in text
 */
function normalizeLineEndings(text: string): string;

/**
 * Creates generated-from comment
 */
function createGeneratedFromComment(
  sourceFile: ts.SourceFile,
  originalCommentRange: ts.CommentRange
): ts.SynthesizedComment;

JSDoc Transformation

Main JSDoc Transformer

The primary transformer that processes JSDoc comments throughout the compilation.

/**
 * Main JSDoc transformer factory
 */
function jsdocTransformer(
  host: AnnotatorHost,
  tsOptions: ts.CompilerOptions,
  typeChecker: ts.TypeChecker,
  diagnostics: ts.Diagnostic[]
): ts.TransformerFactory<ts.SourceFile>;

Type Assertion Removal

Transformer for removing TypeScript type assertions while preserving runtime behavior.

/**
 * Creates transformer to remove type assertions
 */
function removeTypeAssertions(): ts.TransformerFactory<ts.SourceFile>;

Template and Heritage Clause Processing

Functions for adding template and heritage information to JSDoc.

/**
 * Adds template clause to JSDoc if needed
 */
function maybeAddTemplateClause(tags: Tag[], node: ts.Node): void;

/**
 * Adds heritage clauses to JSDoc
 */
function maybeAddHeritageClauses(tags: Tag[], classDecl: ts.ClassDeclaration): void;

/**
 * Escapes text for use in comments
 */
function escapeForComment(str: string): string;

File Overview Comments

File Overview Transformer

Specialized transformer for adding file overview comments with suppressions.

/**
 * Creates transformer for fileoverview comments with suppressions
 */
function transformFileoverviewCommentFactory(
  options: ts.CompilerOptions,
  diagnostics: ts.Diagnostic[],
  generateExtraSuppressions: boolean
): ts.TransformerFactory<ts.SourceFile>;

Usage Example:

// Generates fileoverview comments like:
/**
 * @fileoverview This file was generated from TypeScript sources.
 * @suppress {checkTypes,constantProperty,extraRequire,missingOverride,missingReturn,unusedPrivateMembers,uselessCode}
 */

Tag Processing

Conflict Detection

Detection of JSDoc tags that conflict with type annotations.

/**
 * Set of JSDoc tag names that conflict with type annotations
 */
const TAGS_CONFLICTING_WITH_TYPE: Set<string>;

Common conflicting tags include:

@type - Conflicts with TypeScript type annotations
@param type information - Handled by type translator
@return type information - Generated from TypeScript return types

Tag Transformation Examples

// Before transformation (TypeScript)
/**
 * Processes user data
 * @param userData - The user information
 */
function processUser(userData: UserData): Promise<ProcessedUser> {
  // ...
}

// After transformation (Closure-compatible JSDoc)
/**
 * Processes user data
 * @param {!UserData} userData - The user information
 * @return {!Promise<!ProcessedUser>}
 */
function processUser(userData) {
  // ...
}

Integration with Type System

JSDoc processing integrates closely with the type translation system:

Type Annotation Generation

// TypeScript generic function
function map<T, U>(items: T[], fn: (item: T) => U): U[] {
  return items.map(fn);
}

// Generated JSDoc with template tags
/**
 * @template T, U
 * @param {!Array<T>} items
 * @param {function(T): U} fn
 * @return {!Array<U>}
 */
function map(items, fn) {
  return items.map(fn);
}

Class Documentation

// TypeScript class
/**
 * Represents a user in the system
 */
class User implements Serializable {
  constructor(public name: string, public age: number) {}
  
  serialize(): string {
    return JSON.stringify(this);
  }
}

// Generated JSDoc
/**
 * Represents a user in the system
 * @implements {Serializable}
 */
class User {
  /** @param {string} name @param {number} age */
  constructor(name, age) {
    this.name = name;
    this.age = age;
  }
  
  /** @return {string} */
  serialize() {
    return JSON.stringify(this);
  }
}