or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

build.md cli-commands.md index.md input-processing.md lint.md output-formats.md utilities.md

tile.json

Documentation Generation

Core functionality for building documentation from JavaScript source code with JSDoc annotations. Provides comprehensive configuration options and intelligent inference of code structure and relationships.

Capabilities

Build Function

Generates JavaScript documentation as parsed JSDoc comments from source files with full dependency resolution and inference.

/**
 * Generate JavaScript documentation as a list of parsed JSDoc comments
 * @param indexes - Files to process (string or array of strings)
 * @param args - Configuration options for documentation generation
 * @returns Promise that resolves to array of parsed comments
 */
function build(
  indexes: string[] | string,
  args: BuildOptions
): Promise<Comment[]>;

interface BuildOptions {
  /** String regex/glob pattern for external modules to include */
  external?: string[];
  /** Whether to avoid dependency parsing in JavaScript code */
  shallow?: boolean;
  /** Array defining sorting order of documentation */
  order?: (string | object)[];
  /** Array of access levels to output in documentation */
  access?: string[];
  /** Highlight.js configuration options */
  hljs?: HljsOptions;
  /** Regular expression to infer private elements from naming */
  inferPrivate?: string;
  /** Additional file extensions to treat as JavaScript */
  extension?: string | string[];
  /** GitHub integration for source code linking */
  github?: boolean;
  /** Theme name for HTML output */
  theme?: string;
  /** Project name for documentation */
  name?: string;
  /** Project version for documentation */
  version?: string;
  /** Project description for documentation */
  description?: string;
  /** Project homepage for documentation */
  homepage?: string;
  /** Favicon path for HTML output */
  favicon?: string;
  /** Whether to document only exported values */
  documentExported?: boolean;
  /** Configuration file path */
  config?: string;
  /** Markdown table of contents generation */
  markdownToc?: boolean;
  /** Maximum depth for Markdown table of contents */
  markdownTocMaxDepth?: number;
  /** Parse additional file extensions */
  parseExtension?: string[];
  /** Additional extensions for require() search algorithm */
  requireExtension?: string[];
  /** Path to babel configuration file */
  babel?: string;
  /** Don't use package.json for configuration defaults */
  noPackage?: boolean;
  /** Dependency resolution algorithm: 'browser' or 'node' */
  resolve?: string;
  /** Watch files and rebuild on changes */
  watch?: boolean;
  /** Output directory or file path */
  output?: string;
  /** Output format */
  format?: string;
}

interface HljsOptions {
  /** Automatically detect programming language */
  highlightAuto?: boolean;
  /** Languages for highlight.js to choose from */
  languages?: string[];
}

Usage Examples:

import { build } from "documentation";

// Basic documentation generation
const comments = await build(['index.js'], {
  access: ['public']
});

// Advanced configuration with GitHub integration
const comments = await build(['src/**/*.js'], {
  external: ['lodash', 'express'],
  shallow: false,
  access: ['public', 'protected'],
  github: true,
  theme: 'default',
  name: 'My Project',
  version: '1.0.0',
  inferPrivate: '^_',
  hljs: {
    highlightAuto: true,
    languages: ['javascript', 'typescript']
  }
});

// Document only exported values
const exportedComments = await build(['lib/index.js'], {
  documentExported: true,
  shallow: true
});

Configuration Options

Access Control

Control which documentation elements are included based on their access level:

public - Explicitly marked as public
protected - Explicitly marked as protected
private - Explicitly marked as private
undefined - No explicit access level specified

const comments = await build(['src/'], {
  access: ['public', 'protected'] // Exclude private and undefined
});

Dependency Handling

Configure how the tool processes file dependencies:

// Deep dependency parsing (default)
const comments = await build(['index.js'], {
  shallow: false
});

// Shallow parsing - only specified files
const comments = await build(['index.js'], {
  shallow: true
});

// External module inclusion
const comments = await build(['index.js'], {
  external: ['lodash.*', 'express']
});

Sorting and Organization

Control the order and organization of generated documentation:

const comments = await build(['src/'], {
  order: [
    'MyClass',
    'MyClass.method1',
    'MyClass.method2',
    { 'kind': 'function' },
    { 'kind': 'class' }
  ]
});

Type Inference

Configure automatic inference of private members and code structure:

const comments = await build(['src/'], {
  // Treat methods starting with _ as private
  inferPrivate: '^_',
  
  // Additional file extensions
  extension: ['ts', 'tsx', 'vue']
});

GitHub Integration

Enable automatic linking to source code on GitHub:

const comments = await build(['src/'], {
  github: true // Automatically detects GitHub repository
});

This adds source code links to each documented element, making it easy to navigate from documentation to implementation.

Syntax Highlighting

Configure syntax highlighting for code examples in HTML output:

const comments = await build(['src/'], {
  hljs: {
    highlightAuto: true,
    languages: ['javascript', 'typescript', 'json', 'bash']
  }
});

Return Value

The build function returns a Promise that resolves to an array of Comment objects representing the parsed documentation. Each comment contains:

Metadata: Name, kind, access level, location information
Documentation: Description, parameters, return values, examples
Code Context: AST nodes, source code snippets, file paths
Relationships: Inheritance, implementation, membership information
Inferred Data: Types, parameter names, default values

The resulting comments can be passed to any output format function for rendering.