tessl/npm-jsdoc

API documentation generator for JavaScript that parses source code and JSDoc comments to produce HTML documentation

—

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

Utilities

Name: tessl/npm-jsdoc
Author: tessl

JSDoc provides a comprehensive set of utility modules for common operations including logging, data manipulation, debugging, and template helpers.

Capabilities

Logging

Central logging system with configurable levels and output formatting.

/**
 * Logger instance with level-based output
 */
const logger = {
  /** Log levels: TRACE, DEBUG, INFO, WARN, ERROR, FATAL */
  LEVELS: {
    TRACE: 10;
    DEBUG: 20;
    INFO: 30;
    WARN: 40;
    ERROR: 50;
    FATAL: 60;
  };
  
  /**
   * Set the minimum logging level
   * @param level - Logging level or level name
   */
  setLevel(level: number | string): void;
  
  /**
   * Get current logging level
   * @returns Current logging level
   */
  getLevel(): number;
  
  /**
   * Log functions for each level
   */
  trace(message: string, ...args: any[]): void;
  debug(message: string, ...args: any[]): void;
  info(message: string, ...args: any[]): void;
  warn(message: string, ...args: any[]): void;
  error(message: string, ...args: any[]): void;
  fatal(message: string, ...args: any[]): void;
};

Deep Object Operations

Utilities for deep copying and manipulating complex object structures.

/**
 * Deep object operations utility
 * @param original - Original object to copy
 * @param extra - Additional properties to merge
 * @returns Deep copied object with merged properties
 */
function doop(original: object, extra?: object): object;

Debug Output

Debugging utilities for safely dumping object structures to console.

/**
 * Safely dump objects to string format for debugging
 * @param objects - Objects to dump
 * @returns Formatted string representation
 */
function dump(objects: any[]): string;

Error Handling

Centralized error handling and processing utilities.

/**
 * Handle errors with consistent logging and formatting
 * @param error - Error object or message
 * @param context - Additional context information
 */
function handle(error: Error | string, context?: string): void;

Type Casting

Utilities for converting and casting values between types.

/**
 * Cast values to appropriate types based on JSDoc type expressions
 * @param value - Value to cast
 * @param type - Target type expression
 * @returns Casted value
 */
function cast(value: any, type: string): any;

Markdown Processing

Markdown parsing and conversion utilities for JSDoc comments.

/**
 * Parse markdown content and convert to HTML
 * @param source - Markdown source text
 * @returns HTML string
 */
function parse(source: string): string;

/**
 * Get markdown renderer instance
 * @returns Configured markdown-it renderer
 */
function getRenderer(): any;

BOM Stripping

Utility for removing Byte Order Mark from file content.

/**
 * Strip BOM from file content
 * @param text - File content with potential BOM
 * @returns Content with BOM removed
 */
function strip(text: string): string;

Template Helpers

Comprehensive template helper functions for generating documentation output.

/**
 * Template helper functions for documentation generation
 */
const templateHelper = {
  /**
   * Set tutorials for template use
   * @param tutorials - Tutorial root object
   */
  setTutorials(tutorials: TutorialRoot): void;
  
  /**
   * Convert longname to URL
   * @param longname - Symbol longname
   * @returns URL string
   */
  longnameToUrl(longname: string): string;
  
  /**
   * Create link to symbol
   * @param longname - Symbol longname
   * @param linkText - Link display text
   * @returns HTML link element
   */
  linkto(longname: string, linkText?: string): string;
  
  /**
   * Make string HTML-safe
   * @param str - String to escape
   * @returns HTML-escaped string
   */
  htmlsafe(str: string): string;
  
  /**
   * Resolve author links in text
   * @param text - Text with author information
   * @returns Text with resolved links
   */
  resolveAuthorLinks(text: string): string;
  
  /**
   * Get CSS class name for access level
   * @param doclet - Doclet with access information
   * @returns CSS class string
   */
  getAccessClass(doclet: Doclet): string;
  
  /**
   * Find doclets matching criteria
   * @param spec - Search specification
   * @returns Array of matching doclets
   */
  find(spec: object): Doclet[];
  
  /**
   * Get signature for function doclet
   * @param doclet - Function doclet
   * @returns Function signature string
   */
  getSignature(doclet: Doclet): string;
  
  /**
   * Get ancestors array for doclet
   * @param doclet - Doclet to get ancestors for
   * @returns Array of ancestor doclets
   */
  getAncestors(doclet: Doclet): Doclet[];
  
  /**
   * Get members of specified kinds
   * @param data - TaffyDB data collection
   * @param kind - Member kind to filter by
   * @returns Filtered members
   */
  getMembers(data: TaffyDB, kind: string): any;
  
  /**
   * Get namespace signature
   * @param doclet - Namespace doclet
   * @returns Namespace signature string
   */
  getNamespaceSignature(doclet: Doclet): string;
  
  /**
   * Convert scope to punctuation
   * @param scope - Scope string
   * @returns Punctuation character
   */
  scopeToPunc(scope: string): string;
  
  /**
   * Register link for symbol
   * @param longname - Symbol longname
   * @param url - URL to register
   */
  registerLink(longname: string, url: string): void;
  
  /**
   * Check if symbol is external
   * @param longname - Symbol longname
   * @returns True if external
   */
  isExternal(longname: string): boolean;
};

AST Node Utilities

Utilities for working with Abstract Syntax Tree nodes during parsing.

/**
 * AST node manipulation utilities
 */
const astnode = {
  /**
   * Get node by ID
   * @param nodeId - Unique node identifier
   * @returns AST node object
   */
  getById(nodeId: string): ASTNode;
  
  /**
   * Add node to tracking system
   * @param node - AST node to track
   * @returns Assigned node ID
   */
  addNode(node: ASTNode): string;
  
  /**
   * Get parent node
   * @param node - Child node
   * @returns Parent AST node
   */
  getParent(node: ASTNode): ASTNode;
  
  /**
   * Check if node is of specified type
   * @param node - AST node to check
   * @param type - Node type string
   * @returns True if node matches type
   */
  isType(node: ASTNode, type: string): boolean;
};

AST Builder

Utilities for building and manipulating Abstract Syntax Trees.

/**
 * AST building utilities
 */
const astbuilder = {
  /**
   * Build AST from source code
   * @param source - JavaScript source code
   * @param filename - Source filename
   * @returns AST root node
   */
  build(source: string, filename: string): ASTNode;
  
  /**
   * Add parent references to AST nodes
   * @param node - Root AST node
   */
  addParentReferences(node: ASTNode): void;
  
  /**
   * Add scope information to nodes
   * @param node - Root AST node
   */
  addScopes(node: ASTNode): void;
};

Syntax Definitions

JavaScript syntax and parsing configuration utilities.

/**
 * JavaScript syntax configuration
 */
const syntax = {
  /** Babel parser options for JavaScript */
  jsParser: object;
  
  /** File extensions to process */
  extensions: string[];
  
  /**
   * Get parser options for file type
   * @param filename - File to parse
   * @returns Parser configuration
   */
  getParserOptions(filename: string): object;
};

File System Utilities

Enhanced file system operations with JSDoc-specific functionality.

/**
 * Enhanced filesystem operations
 */
const fs = {
  /**
   * Read file with encoding detection
   * @param filepath - Path to file
   * @param encoding - File encoding
   * @returns File contents
   */
  readFileSync(filepath: string, encoding?: string): string;
  
  /**
   * Write file with directory creation
   * @param filepath - Path to file
   * @param content - Content to write
   * @param encoding - File encoding
   */
  writeFileSync(filepath: string, content: string, encoding?: string): void;
  
  /**
   * Get file statistics
   * @param filepath - Path to file
   * @returns File stats object
   */
  statSync(filepath: string): object;
  
  /**
   * List directory contents
   * @param dirpath - Directory path
   * @returns Array of file/directory names
   */
  readdirSync(dirpath: string): string[];
};

Path Utilities

Path manipulation utilities with JSDoc-specific enhancements.

/**
 * Path manipulation utilities
 */
const path = {
  /**
   * Normalize file paths for cross-platform compatibility
   * @param filepath - Path to normalize
   * @returns Normalized path
   */
  normalize(filepath: string): string;
  
  /**
   * Join path segments
   * @param segments - Path segments to join
   * @returns Joined path
   */
  join(...segments: string[]): string;
  
  /**
   * Get file extension
   * @param filepath - File path
   * @returns File extension including dot
   */
  extname(filepath: string): string;
  
  /**
   * Get directory name
   * @param filepath - File path
   * @returns Directory path
   */
  dirname(filepath: string): string;
  
  /**
   * Get base filename
   * @param filepath - File path
   * @param ext - Extension to remove
   * @returns Base filename
   */
  basename(filepath: string, ext?: string): string;
};

Usage Examples

Basic Logging

const logger = require('jsdoc/util/logger');

// Set logging level
logger.setLevel('DEBUG');

// Log messages
logger.info('Starting documentation generation');
logger.warn('Deprecated tag usage detected');
logger.error('Parse error in file:', filename);

Template Helpers

const helper = require('jsdoc/util/templateHelper');

// In template publish function
function publish(data, opts) {
  const classes = helper.find(data, { kind: 'class' });
  
  classes.forEach(cls => {
    const url = helper.longnameToUrl(cls.longname);
    const link = helper.linkto(cls.longname, cls.name);
    const signature = helper.getSignature(cls);
    
    console.log(`Class: ${link} -> ${url}`);
  });
}

Deep Object Operations

const doop = require('jsdoc/util/doop');

// Deep copy with additional properties
const originalConfig = { source: { include: ['src/'] } };
const modifiedConfig = doop(originalConfig, {
  source: { exclude: ['test/'] }
});

// Original remains unchanged
console.log(originalConfig.source.exclude); // undefined
console.log(modifiedConfig.source.exclude); // ['test/']

Debug Output

const dumper = require('jsdoc/util/dumper');

// Safely dump complex objects
const complexObject = { 
  circular: null,
  data: [1, 2, 3],
  nested: { deep: { value: 'test' } }
};
complexObject.circular = complexObject; // Create circular reference

console.log(dumper.dump([complexObject])); // Safe output

Markdown Processing

const markdown = require('jsdoc/util/markdown');

// Process markdown in doclets
function processDoclet(doclet) {
  if (doclet.description) {
    doclet.description = markdown.parse(doclet.description);
  }
  
  if (doclet.summary) {
    doclet.summary = markdown.parse(doclet.summary);
  }
}

Integration with Core Systems

Parser Integration

Utilities are automatically available within the parser system:

const parser = require('jsdoc/src/parser');
const logger = require('jsdoc/util/logger');

const jsdocParser = parser.createParser();

jsdocParser.on('parseBegin', (e) => {
  logger.info(`Starting parse of ${e.sourcefiles.length} files`);
});

jsdocParser.on('newDoclet', (e) => {
  if (e.doclet.undocumented) {
    logger.warn(`Undocumented symbol: ${e.doclet.longname}`);
  }
});

Plugin Development

Utilities are essential for plugin development:

// my-plugin.js
const logger = require('jsdoc/util/logger');
const helper = require('jsdoc/util/templateHelper');

exports.handlers = {
  newDoclet: function(e) {
    logger.debug(`Processing doclet: ${e.doclet.longname}`);
    
    if (e.doclet.kind === 'function') {
      const signature = helper.getSignature(e.doclet);
      e.doclet.customSignature = signature;
    }
  }
};

Template Development

Template helpers are the foundation of custom templates:

// template publish function
const helper = require('jsdoc/util/templateHelper');

function publish(data, opts) {
  // Find all documented symbols
  const documented = helper.find(data, { undocumented: { '!is': true } });
  
  documented.forEach(doclet => {
    const url = helper.longnameToUrl(doclet.longname);
    const ancestors = helper.getAncestors(doclet);
    
    generateDocPage(doclet, url, ancestors);
  });
}

Error Handling

Utility Error Patterns

const error = require('jsdoc/util/error');

try {
  // Risky operation
  processDoclet(doclet);
} catch (e) {
  error.handle(e, `Processing doclet: ${doclet.longname}`);
}

Logging Errors

const logger = require('jsdoc/util/logger');

function safeOperation(data) {
  try {
    return processData(data);
  } catch (e) {
    logger.error('Operation failed:', e.message);
    logger.debug('Stack trace:', e.stack);
    return null;
  }
}