or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

cli.md comment-tags.md configuration.md core-generation.md index.md output-generation.md parsing.md plugins.md

tile.json

Core Documentation Generation

The main API for generating documentation from source files. This is the primary entry point for both command-line and programmatic usage.

Main Function

function createDoc(options: ApiDocOptions): boolean | ApiDocResult;

Generates API documentation from source files based on the provided options.

Parameters:

options (ApiDocOptions): Configuration object for documentation generation

Returns:

true: When there are no source files to process
false: When an error occurs during generation
ApiDocResult: Object containing the generated documentation data

Options Interface

interface ApiDocOptions {
  src: string | string[];
  dest: string;
  template?: string;
  config?: string;
  verbose?: boolean;
  debug?: boolean;
  silent?: boolean;
  single?: boolean;
  dryRun?: boolean;
  apiprivate?: boolean;
  markdown?: boolean | string;
  encoding?: string;
  lineEnding?: string;
  includeFilters?: string[];
  excludeFilters?: string[];
  filters?: Record<string, string>;
  languages?: Record<string, string>;
  parsers?: Record<string, string>;
  workers?: Record<string, string>;
  copyDefinitions?: boolean;
  filterBy?: string;
  logFormat?: 'simple' | 'json';
  warnError?: boolean;
  writeJson?: boolean;
}

Option Details:

src: Input source directories or files (required)
dest: Output directory for generated documentation (required)
template: Path to custom template directory
config: Path to configuration file (JSON or JavaScript)
verbose: Enable verbose logging output
debug: Enable debug mode with detailed logging
silent: Suppress all output except errors
single: Generate single-file HTML output instead of multi-file
dryRun: Parse files but don't write any output
apiprivate: Include APIs marked with @apiPrivate
markdown: Enable/disable markdown parser or path to custom parser
encoding: File encoding (default: 'utf8')
lineEnding: Line ending format ('LF', 'CR', 'CRLF')
includeFilters: RegEx patterns for files to include
excludeFilters: RegEx patterns for files to exclude
filters: Custom filter plugins
languages: Custom language parsers
parsers: Custom API parsers
workers: Custom worker plugins
copyDefinitions: Copy definitions instead of inlining
filterBy: Filter documentation by tag
logFormat: Output format for logs ('simple' or 'json')
warnError: Treat warnings as errors
writeJson: Generate api-data.json file

Result Interface

interface ApiDocResult {
  data: string;
  project: string;
}

data: JSON string containing parsed API data
project: JSON string containing project information

Usage Examples

Basic Usage

const { createDoc } = require('apidoc');

const result = createDoc({
  src: ['./src', './lib'],
  dest: './documentation'
});

if (result === false) {
  console.error('Documentation generation failed');
  process.exit(1);
} else if (result === true) {
  console.log('No files to process');
} else {
  console.log('Documentation generated successfully');
}

Advanced Configuration

const { createDoc } = require('apidoc');

const result = createDoc({
  src: ['./src'],
  dest: './docs',
  template: './custom-template',
  config: './apidoc.json',
  verbose: true,
  debug: false,
  single: false,
  apiprivate: false,
  markdown: true,
  encoding: 'utf8',
  includeFilters: ['.*\\.(js|ts)$'],
  excludeFilters: ['node_modules', 'test'],
  writeJson: true,
  warnError: true
});

Dry Run Mode

const { createDoc } = require('apidoc');

// Parse files but don't generate output
const result = createDoc({
  src: ['./src'],
  dest: './docs',
  dryRun: true,
  verbose: true
});

if (result !== false) {
  console.log('Source files parsed successfully');
}

Single File Output

const { createDoc } = require('apidoc');

const result = createDoc({
  src: ['./src'],
  dest: './docs/api.html',
  single: true,
  template: './template'
});

Error Handling

The function returns false when errors occur. Common error scenarios:

File Access Errors: Source files cannot be read
Configuration Errors: Invalid configuration file or options
Template Errors: Custom template cannot be loaded or processed
Parser Errors: Source code cannot be parsed
Output Errors: Cannot write to destination directory

Integration with Build Systems

npm Scripts

{
  "scripts": {
    "docs": "apidoc -i src/ -o docs/",
    "docs:watch": "apidoc -i src/ -o docs/ --watch",
    "docs:single": "apidoc -i src/ -o docs/api.html --single"
  }
}

Programmatic Build Integration

const { createDoc } = require('apidoc');

function buildDocs() {
  console.log('Building API documentation...');
  
  const result = createDoc({
    src: ['./src'],
    dest: './build/docs',
    verbose: process.env.NODE_ENV === 'development'
  });
  
  if (result === false) {
    throw new Error('Documentation build failed');
  }
  
  console.log('API documentation built successfully');
  return result;
}

module.exports = { buildDocs };