or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

category-organization.mdcomponent-bundling.mdcomponent-documentation.mdcontent-loading.mdindex.mdtheme-engine.mdtypedef-import.mdtypescript-support.md
tile.json

typescript-support.mddocs/

TypeScript Support

Automatic conversion of TypeScript constructs to JSDoc-compatible documentation, including type aliases, interfaces, and class members.

Capabilities

Type Converter

Main function that converts TypeScript source code to JSDoc-compatible type definitions.

/**
 * Converts TypeScript types to JSDoc format
 * @param {string} src - TypeScript source code to convert
 * @param {string} filename - Source file name (default: 'test.ts')
 * @returns {string} JSDoc-compatible type definitions
 */
function typeConverter(src: string, filename?: string): string;

Usage Example:

const typeConverter = require('better-docs/typescript/type-converter');

const tsCode = `
/**
 * User interface
 */
interface User {
  /** User's name */
  name: string;
  /** User's age */
  age?: number;
}
`;

const jsdocCode = typeConverter(tsCode, 'user.ts');
// Generates JSDoc @interface and @property tags

JSDoc Event Handlers

Event handlers for processing TypeScript files during JSDoc parsing.

interface TypeScriptHandlers {
  /**
   * Processes TypeScript files before JSDoc parsing
   * @param {Object} e - Parse event containing filename and source
   */
  beforeParse(e: ParseEvent): void;
  
  /**
   * Processes doclets to handle @optional tags
   * @param {Object} docletEvent - Doclet event
   */
  newDoclet(docletEvent: DocletEvent): void;
}

interface ParseEvent {
  filename: string;
  source: string;
}

interface DocletEvent {
  doclet: {
    tags?: Array<{
      title: string;
      value?: string;
    }>;
    optional?: boolean;
  };
}

Type Name Extraction

Extracts type names from TypeScript AST nodes for JSDoc conversion.

/**
 * Extracts type name from TypeScript AST node
 * @param {Object} type - TypeScript type node
 * @param {string} src - Source code for context
 * @returns {string} Type name string
 */
function getTypeName(type: Object, src: string): string;

/**
 * Extracts name from TypeScript AST node
 * @param {Object} node - TypeScript AST node
 * @param {string} src - Source code for context
 * @returns {string} Name string
 */
function getName(node: Object, src: string): string;

/**
 * Debug utility for checking TypeScript node types (development only)
 * @param {Object} node - TypeScript AST node
 */
function checkType(node: Object): void;

Comment Processing

Functions for processing and enhancing JSDoc comments with TypeScript information.

/**
 * Appends content to a JSDoc comment block
 * @param {string} commentBlock - Existing comment block
 * @param {string} toAppend - Content to append
 * @returns {string} Enhanced comment block
 */
function appendComment(commentBlock: string, toAppend: string): string;

/**
 * Fills missing method declaration information
 * @param {string} comment - Existing comment
 * @param {Object} member - TypeScript member node
 * @param {string} src - Source code
 * @returns {string} Enhanced comment
 */
function fillMethodComment(comment: string, member: Object, src: string): string;

/**
 * Extracts comment text from TypeScript member
 * @param {Object} member - TypeScript member node
 * @param {string} src - Source code
 * @returns {string} Comment text
 */
function getCommentAsString(member: Object, src: string): string;

Parameter Conversion

Converts TypeScript function parameters to JSDoc @param tags.

/**
 * Converts function parameters to @param tags
 * @param {string} jsDoc - Existing JSDoc comment
 * @param {Object} node - TypeScript function node
 * @param {string} src - Source code
 * @returns {string} Enhanced JSDoc with @param tags
 */
function convertParams(jsDoc: string, node: Object, src: string): string;

Member Conversion

Converts TypeScript type properties to JSDoc @property tags.

/**
 * Converts type properties to @property tags
 * @param {string} jsDoc - Existing JSDoc comment
 * @param {Object} type - TypeScript type node
 * @param {string} src - Source code
 * @param {string} parentName - Parent element name
 * @returns {string} Enhanced JSDoc with @property tags
 */
function convertMembers(jsDoc: string, type: Object, src: string, parentName?: string): string;

TypeScript Construct Support

Interface Conversion

TypeScript interfaces are converted to JSDoc @interface tags with member documentation:

TypeScript Input:

/**
 * User configuration options
 */
interface UserConfig {
  /** User's display name */
  name: string;
  /** User's email address */
  email?: string;
  /** User's age in years */
  age: number;
}

JSDoc Output:

/**
 * User configuration options
 * @interface UserConfig
 * @property {string} name - User's display name
 * @property {string} [email] - User's email address  
 * @property {number} age - User's age in years
 */

Type Alias Conversion

TypeScript type aliases are converted to JSDoc @typedef tags:

TypeScript Input:

/**
 * Status of a user account
 */
type UserStatus = 'active' | 'inactive' | 'pending';

/**
 * User data structure
 */
type UserData = {
  id: string;
  status: UserStatus;
};

JSDoc Output:

/**
 * Status of a user account
 * @typedef {string} UserStatus
 */

/**
 * User data structure  
 * @typedef {object} UserData
 * @property {string} id
 * @property {UserStatus} status
 */

Class Member Conversion

TypeScript class members with visibility modifiers are converted with appropriate JSDoc tags:

TypeScript Input:

class UserService {
  /**
   * Private user cache
   */
  private cache: Map<string, User>;
  
  /**
   * Protected logger instance
   */
  protected logger: Logger;
  
  /**
   * Public user count
   */
  public userCount: number;
  
  /**
   * Static instance reference
   */
  static instance: UserService;
}

JSDoc Output:

/**
 * Private user cache
 * @private
 * @type {Map}
 */
UserService.prototype.cache

/**
 * Protected logger instance
 * @protected
 * @type {Logger}
 */
UserService.prototype.logger

/**
 * Public user count
 * @public
 * @type {number}
 */
UserService.prototype.userCount

/**
 * Static instance reference
 * @static
 * @type {UserService}
 */
UserService.instance

Function Type Conversion

Function types and method signatures are converted with full parameter and return type information:

TypeScript Input:

/**
 * Processes user data
 */
function processUser(
  /** User data to process */
  userData: UserData,
  /** Processing options */
  options?: ProcessOptions
): Promise<ProcessResult>;

JSDoc Output:

/**
 * Processes user data
 * @method
 * @param {UserData} userData - User data to process
 * @param {ProcessOptions} [options] - Processing options
 * @return {Promise<ProcessResult>}
 */

Configuration

Enable TypeScript support in JSDoc configuration:

{
  "tags": {
    "allowUnknownTags": ["optional"]
  },
  "plugins": [
    "node_modules/better-docs/typescript"
  ],
  "source": {
    "includePattern": "\\.(jsx|js|ts|tsx)$"
  }
}

Supported TypeScript Features

  • Interface declarations with optional properties
  • Type aliases (union types, literal types, object types)
  • Class declarations with visibility modifiers
  • Function declarations with parameter and return types
  • Generic types and type parameters
  • Array types and tuple types
  • Intersection and union types
  • Import type declarations (cleaned up automatically)