tsdoc-comments

When to Use

• Documenting public APIs, functions, classes, or interfaces
• Adding JSDoc/TSDoc comments to existing code
• Creating type documentation for TypeScript projects
• Improving code readability with standardized comments

Critical Patterns

1. Always Use English

All comments MUST be written in English, regardless of the project's primary language.

2. TSDoc Standard Tags

Use TSDoc-compliant tags for consistency:

Tag	Purpose	Example
@param	Document function parameters	@param userId - The unique user identifier
@returns	Document return values	@returns The user object or null
@throws	Document exceptions	@throws {Error} When user not found
@remarks	Additional details	@remarks This is cached for 5 minutes
@example	Usage examples	@example followed by code block
@public	Public API marker	@public
@internal	Internal implementation	@internal
@deprecated	Deprecation notice	@deprecated Use getUserById instead

3. Comment Structure

/**
 * Brief one-line summary (required)
 * 
 * Detailed description if needed (optional)
 * Can span multiple lines.
 * 
 * @param paramName - Parameter description
 * @returns Return value description
 * @throws {ErrorType} When this error occurs
 * 
 * @example
 * ```typescript
 * const result = functionName(param);
 * ```
 */

4. Describe "Why", Not "What"

// ❌ BAD - Describes what the code does (obvious)
/** Increments the counter by 1 */
counter++;

// ✅ GOOD - Explains why
/** Track retry attempts to prevent infinite loops */
counter++;

5. Parameter Descriptions

• Always use hyphen format: @param name - Description
• Include type information when helpful
• Describe constraints or valid ranges

/**
 * @param age - User's age in years (must be 0-150)
 * @param email - Valid email address following RFC 5322
 */

Code Examples

Function Documentation

/**
 * Fetches user data from the API with automatic retry logic
 * 
 * @param userId - Unique identifier for the user
 * @param options - Optional configuration for the request
 * @returns Promise resolving to user data or null if not found
 * @throws {NetworkError} When connection fails after retries
 * @throws {ValidationError} When userId format is invalid
 * 
 * @example
 * ```typescript
 * const user = await fetchUser('user-123', { timeout: 5000 });
 * if (user) {
 *   console.log(user.name);
 * }
 * ```
 */
async function fetchUser(userId: string, options?: RequestOptions): Promise<User | null> {
  // Implementation
}

Class Documentation

/**
 * Manages voice recognition state and audio processing
 * 
 * @remarks
 * This class handles the complete lifecycle of voice interactions,
 * including wake word detection, speech recognition, and audio feedback.
 * All processing happens on-device for privacy.
 * 
 * @public
 */
class VoiceHandler {
  /**
   * Initializes the voice recognition engine
   * 
   * @param config - Voice handler configuration
   * @throws {AudioError} When microphone access is denied
   */
  constructor(config: VoiceConfig) {
    // Implementation
  }
}

Interface Documentation

/**
 * Configuration options for the vision model
 * 
 * @public
 */
interface VisionConfig {
  /**
   * Minimum confidence threshold for object detection (0.0-1.0)
   * @defaultValue 0.6
   */
  confidenceThreshold: number;

  /**
   * Maximum number of objects to detect per frame
   * @defaultValue 10
   */
  maxDetections: number;
}

Deprecated Code

/**
 * Processes image using legacy algorithm
 * 
 * @deprecated Since version 2.0. Use {@link processImageV2} instead.
 * This method will be removed in version 3.0.
 * 
 * @param image - Image buffer to process
 */
function processImage(image: Buffer): Result {
  // Implementation
}

Commands

# Validate TSDoc comments (if using eslint-plugin-tsdoc)
npx eslint --ext .ts,.tsx .

# Generate documentation from TSDoc comments
npx typedoc --out docs src/

# Check for missing documentation
npx tsc --noEmit --strict

Style Guidelines

DO

• Write in present tense: "Returns the user" not "Will return the user"
• Be concise but complete
• Use proper punctuation and grammar
• Include units in parameter descriptions: "timeout in milliseconds"
• Document edge cases and constraints
• Add @example for complex functions

DON'T

• Repeat the function/parameter name: @param user - The user ❌
• Use abbreviations: "auth" → "authentication" ✅
• Write vague descriptions: "Handles the thing" ❌
• Mix languages: All English only
• Document obvious parameters unless there are constraints

Resources

• Templates: See assets/ for comment templates
• TSDoc Specification: https://tsdoc.org/
• ESLint Plugin: eslint-plugin-tsdoc for validation