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

TypeDef Import Plugin

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

TypeScript-style import type cleanup plugin that removes import type declarations from source code before JSDoc processing.

Capabilities

Import Type Cleanup

Removes TypeScript-style import type declarations that would cause JSDoc parsing errors.

interface TypeDefImportHandlers {
  /**
   * Processes source code before JSDoc parsing to remove import type declarations
   * @param {Object} e - Parse event containing source code
   */
  beforeParse(e: ParseEvent): void;
}

interface ParseEvent {
  /** Source file name */
  filename: string;
  /** Source code content */
  source: string;
}

Usage Patterns

Basic Import Type Removal

The plugin automatically removes TypeScript-style import type declarations during JSDoc parsing:

TypeScript Input:

/** @typedef {import('./some-other-file').ExportedType} ExportedType */

/**
 * User service that works with exported types
 * @param {ExportedType} data - Data of exported type
 */
function processData(data) {
  // Implementation
}

Processed Output:

/**
 * User service that works with exported types
 * @param {ExportedType} data - Data of exported type
 */
function processData(data) {
  // Implementation
}

Complex Import Patterns

Handles various import type declaration patterns:

/** @typedef {import('./types/user').User} User */
/** @typedef {import('./types/api').ApiResponse} ApiResponse */
/** @typedef {import('external-lib').LibType} LibType */

/**
 * API service with typed responses
 * @param {User} user - User data
 * @returns {Promise<ApiResponse>} API response
 */
async function callApi(user) {
  // Implementation
}

All @typedef {import(...)} declarations are automatically removed before JSDoc processing.

Integration with TypeScript Plugin

Works seamlessly with the TypeScript plugin to provide complete TypeScript support:

{
  "plugins": [
    "node_modules/better-docs/typescript",
    "node_modules/better-docs/typedef-import"
  ]
}

The typedef-import plugin cleans up import declarations while the TypeScript plugin converts TypeScript constructs to JSDoc format.

Configuration

Enable the typedef-import plugin in JSDoc configuration:

{
  "plugins": [
    "node_modules/better-docs/typedef-import"
  ]
}

No additional configuration is required - the plugin automatically processes all source files during JSDoc parsing.

Use Cases

Legacy TypeScript Support

When working with older TypeScript codebases that use import type declarations in JSDoc comments:

/**
 * Legacy service with import types
 * @typedef {import('./legacy-types').OldType} OldType
 * @param {OldType} data - Legacy data structure
 */
function legacyFunction(data) {
  // Implementation
}

Mixed Codebases

In projects mixing JavaScript and TypeScript where some files use import type declarations:

// mixed-service.js
/**
 * @typedef {import('./types.ts').ServiceConfig} ServiceConfig
 * @param {ServiceConfig} config - Service configuration
 */
function initializeService(config) {
  // Implementation
}

External Library Types

When referencing types from external libraries in JSDoc comments:

/**
 * @typedef {import('express').Request} ExpressRequest
 * @typedef {import('express').Response} ExpressResponse
 * 
 * Express route handler
 * @param {ExpressRequest} req - Express request
 * @param {ExpressResponse} res - Express response
 */
function routeHandler(req, res) {
  // Implementation
}

Processing Details

Regex Pattern

The plugin uses a specific regex pattern to identify and remove import type declarations:

/\/\*\*\s*?@typedef\s*?{\s*?import.*\*\//g

This pattern matches:

JSDoc comment blocks starting with /**
@typedef tags
Import declarations in curly braces {import(...)}
Complete comment blocks ending with */

Multi-line Support

Handles single-line and multi-line import type declarations:

/** @typedef {import('./types').Type} Type */

/**
 * @typedef {import('./complex-types').ComplexType} ComplexType
 */

/**
 * Multi-line typedef with import
 * @typedef {import('./deep/nested/types').DeepType} DeepType
 * Some additional documentation
 */

All patterns are automatically detected and removed.

Best Practices

Prefer TypeScript Plugin

For new projects, use the TypeScript plugin instead of manual import type declarations:

// Recommended: Use TypeScript plugin
interface UserData {
  name: string;
  email: string;
}

// Avoid: Manual import type declarations
/** @typedef {import('./types').UserData} UserData */

Clean Migration

When migrating from import type declarations to full TypeScript support:

Enable both plugins initially
Gradually convert import declarations to native TypeScript
Remove typedef-import plugin once migration is complete

Documentation Consistency

Keep type documentation consistent across the codebase:

// Good: Clear type documentation
/**
 * Processes user data
 * @param {UserData} data - User information object
 * @returns {ProcessedUser} Processed user data
 */

// Avoid: Mixed approaches
/**
 * @typedef {import('./types').UserData} UserData
 * @param {UserData} data - User information
 */