tessl/npm-documentation

A comprehensive JavaScript documentation generator that transforms JSDoc-annotated source code into human-readable documentation in multiple formats

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Utilities

Name: tessl/npm-documentation
Author: tessl

Helper utilities and classes for custom documentation processing, theme development, and advanced formatting operations.

Capabilities

Utility Functions and Classes

Collection of utility tools for extending and customizing documentation generation.

/**
 * Utility functions and classes for documentation processing
 */
interface Util {
  /** Create formatting utilities for HTML output */
  createFormatters(getHref: (href: string) => string): Formatters;
  /** Linker stack class for namespace resolution */
  LinkerStack: typeof LinkerStack;
}

/**
 * Formatting utilities for HTML output generation
 */
interface Formatters {
  /** Format parameter names and types */
  parameter(param: Parameter, short?: boolean): string;
  /** Convert Markdown AST to HTML */
  markdown(ast: object): string;
  /** Format type information as HTML */
  type(type: Type): string;
  /** Automatically link text references */
  autolink(text: string): string;
  /** Format function parameters list */
  parameters(section: Comment, short?: boolean): string;
}

/**
 * Namespace linking and resolution management
 */
class LinkerStack {
  constructor(config: Config);
  /** Add namespace resolution to the stack */
  namespaceResolver(comments: Comment[], resolver: Function): LinkerStack;
  /** Resolve namespace path to URL */
  link(namepath: string): string | undefined;
}

Formatters

Utility functions for formatting documentation elements in HTML output, primarily used in theme development.

Create Formatters Function

Creates a set of formatting utilities with customizable link generation.

/**
 * Create formatting utilities for HTML output
 * @param getHref - Function to generate URLs for cross-references
 * @returns Object containing formatting functions
 */
function createFormatters(getHref: (href: string) => string): Formatters;

Usage Examples:

import { util } from "documentation";

// Create formatters with custom link generator
const getHref = (href) => `./api/${href}.html`;
const formatters = util.createFormatters(getHref);

// Format a parameter
const paramHtml = formatters.parameter({
  name: 'options',
  type: { type: 'NameExpression', name: 'Object' },
  description: { type: 'root', children: [{ type: 'text', value: 'Configuration options' }] },
  optional: true
}, false);

// Format type information
const typeHtml = formatters.type({
  type: 'NameExpression',
  name: 'Promise'
});

// Auto-link text with references
const linkedText = formatters.autolink('See {@link MyClass#method} for details');

Formatter Functions

Parameter Formatting

Format function parameters with types, names, and descriptions:

/**
 * Format parameter names and types
 * @param param - Parameter object with name, type, and description
 * @param short - Whether to use short format (name and type only)
 * @returns HTML string for parameter display
 */
parameter(param: Parameter, short?: boolean): string;

Usage:

const paramHtml = formatters.parameter({
  name: 'callback',
  type: { type: 'FunctionType', params: [], result: { type: 'VoidType' } },
  optional: false,
  description: { type: 'root', children: [{ type: 'text', value: 'Callback function' }] }
});
// Result: '<code>callback</code> <em>(Function)</em> — Callback function'

Type Formatting

Format type expressions as HTML with proper linking:

/**
 * Format type information as HTML
 * @param type - Type expression object
 * @returns HTML string for type display
 */
type(type: Type): string;

Usage:

const typeHtml = formatters.type({
  type: 'UnionType',
  elements: [
    { type: 'NameExpression', name: 'string' },
    { type: 'NameExpression', name: 'number' }
  ]
});
// Result: '<code>string</code> | <code>number</code>'

Markdown Conversion

Convert Markdown AST to HTML:

/**
 * Convert Markdown AST to HTML
 * @param ast - Markdown AST object
 * @returns HTML string
 */
markdown(ast: object): string;

Auto-linking

Automatically convert text references to links:

/**
 * Automatically link text references
 * @param text - Text containing potential references
 * @returns HTML string with links
 */
autolink(text: string): string;

Parameters List

Format complete parameter lists for functions:

/**
 * Format function parameters list
 * @param section - Comment object containing parameters
 * @param short - Whether to use short format
 * @returns HTML string for parameters list
 */
parameters(section: Comment, short?: boolean): string;

LinkerStack Class

Manages namespace resolution and URL linking for cross-references in documentation.

Constructor

Create a new LinkerStack instance with configuration:

/**
 * Create a LinkerStack for namespace resolution
 * @param config - Configuration object
 */
constructor(config: Config);

Usage Examples:

import { util } from "documentation";

// Create LinkerStack with configuration
const linker = new util.LinkerStack({
  github: true,
  name: 'my-project'
});

// Add namespace resolver
const resolver = (name) => {
  if (name.startsWith('MyClass')) {
    return './classes/MyClass.html';
  }
  return undefined;
};

linker.namespaceResolver(comments, resolver);

// Resolve namespace to URL
const url = linker.link('MyClass#method');
console.log(url); // './classes/MyClass.html#method'

Namespace Resolution

Add custom namespace resolvers to the stack:

/**
 * Add namespace resolution to the stack
 * @param comments - Array of parsed comments
 * @param resolver - Function to resolve names to URLs
 * @returns LinkerStack instance for chaining
 */
namespaceResolver(comments: Comment[], resolver: Function): LinkerStack;

Usage:

const linker = new util.LinkerStack(config);

// Add multiple resolvers
linker
  .namespaceResolver(classComments, (name) => `./classes/${name}.html`)
  .namespaceResolver(functionComments, (name) => `./functions/${name}.html`)
  .namespaceResolver(typeComments, (name) => `./types/${name}.html`);

Link Resolution

Resolve namespace paths to URLs:

/**
 * Resolve namespace path to URL
 * @param namepath - Namespace path to resolve
 * @returns URL string or undefined if not found
 */
link(namepath: string): string | undefined;

Usage:

const url = linker.link('MyClass#method');
const moduleUrl = linker.link('utils.helper');
const typeUrl = linker.link('UserConfig');

Advanced Linking Patterns

Class Method Linking

const resolver = (namepath) => {
  const [className, methodName] = namepath.split('#');
  if (methodName) {
    return `./classes/${className}.html#${methodName}`;
  }
  return `./classes/${className}.html`;
};

Module-based Linking

const resolver = (namepath) => {
  const parts = namepath.split('.');
  const moduleName = parts[0];
  const memberName = parts.slice(1).join('.');
  
  if (memberName) {
    return `./modules/${moduleName}.html#${memberName}`;
  }
  return `./modules/${moduleName}.html`;
};

Type Definition Linking

const resolver = (namepath) => {
  if (namepath.endsWith('Config') || namepath.endsWith('Options')) {
    return `./types.html#${namepath}`;
  }
  return undefined;
};

Custom Theme Development

The utilities are essential for developing custom documentation themes:

import { util } from "documentation";

// Theme function using utilities
function customTheme(comments, config) {
  const getHref = (href) => `./${href}.html`;
  const formatters = util.createFormatters(getHref);
  const linker = new util.LinkerStack(config);
  
  // Add resolvers
  linker.namespaceResolver(comments, (name) => {
    // Custom resolution logic
    return formatters.autolink(name);
  });
  
  // Generate HTML using formatters
  const html = comments.map(comment => {
    const params = formatters.parameters(comment);
    const type = comment.returns ? formatters.type(comment.returns[0].type) : '';
    
    return `
      <div class="api-item">
        <h3>${comment.name}</h3>
        <div class="parameters">${params}</div>
        <div class="return-type">${type}</div>
      </div>
    `;
  }).join('');
  
  return html;
}

Integration with Processing Pipeline

Utilities integrate with the main documentation processing pipeline:

import { build, util } from "documentation";

async function generateCustomDocs(files) {
  // Build documentation
  const comments = await build(files, { access: ['public'] });
  
  // Create utilities
  const formatters = util.createFormatters(href => `./${href}.html`);
  const linker = new util.LinkerStack({ github: true });
  
  // Process comments with utilities
  const processedComments = comments.map(comment => {
    return {
      ...comment,
      formattedParams: formatters.parameters(comment),
      linkedDescription: formatters.autolink(comment.description)
    };
  });
  
  return processedComments;
}

Install with Tessl CLI