tessl/npm-better-docs

JSDoc theme that provides TypeScript support, component documentation with live previews, and enhanced categorization features

—

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

TypeScript Support

Name: tessl/npm-better-docs
Author: tessl

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)$"
  }
}