Helper utilities and classes for custom documentation processing, theme development, and advanced formatting operations.
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;
}Utility functions for formatting documentation elements in HTML output, primarily used in theme development.
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');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'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>'Convert Markdown AST to HTML:
/**
* Convert Markdown AST to HTML
* @param ast - Markdown AST object
* @returns HTML string
*/
markdown(ast: object): string;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;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;Manages namespace resolution and URL linking for cross-references in documentation.
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'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`);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');const resolver = (namepath) => {
const [className, methodName] = namepath.split('#');
if (methodName) {
return `./classes/${className}.html#${methodName}`;
}
return `./classes/${className}.html`;
};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`;
};const resolver = (namepath) => {
if (namepath.endsWith('Config') || namepath.endsWith('Options')) {
return `./types.html#${namepath}`;
}
return undefined;
};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;
}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;
}