or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdcomment-tags.mdconfiguration.mdcore-generation.mdindex.mdoutput-generation.mdparsing.mdplugins.md
tile.json

tessl/npm-apidoc

RESTful web API Documentation Generator that creates beautiful, interactive documentation from specially formatted comments in source code

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/apidoc@1.2.x

To install, run

npx @tessl/cli install tessl/npm-apidoc@1.2.0

index.mddocs/

ApiDoc

ApiDoc is a RESTful web API Documentation Generator that creates beautiful, interactive documentation from specially formatted comments in source code. It parses API documentation from source files in multiple programming languages and generates static HTML documentation with examples, parameter descriptions, and response formatting.

Package Information

  • Package Name: apidoc
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install -g apidoc or npm install apidoc

Core Imports

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

For ES modules:

import { createDoc } from 'apidoc';

Basic Usage

Command Line Interface

# Generate documentation from source files
apidoc -i src/ -o doc/

# With configuration file
apidoc -c apidoc.json -i src/ -o doc/

# Watch mode for development
apidoc -i src/ -o doc/ --watch

Programmatic API

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

const result = createDoc({
  src: ['./src'],
  dest: './doc',
  verbose: true
});

if (result === false) {
  console.error('Error generating documentation');
} else if (result === true) {
  console.log('Nothing to do');
} else {
  console.log('Documentation generated successfully');
}

Architecture

ApiDoc is built around several key components:

  • Parser System: Extracts API documentation from specially formatted comments in source code
  • Template Engine: Generates HTML output using Handlebars templates and asset bundling
  • Multi-language Support: Recognizes comment patterns in JavaScript, Java, PHP, Python, Ruby, and many other languages
  • Plugin Architecture: Extensible system for custom parsers, workers, filters, and language support
  • Configuration System: Flexible configuration via JSON files, JavaScript files, or package.json

Capabilities

Core Documentation Generation

Main API for generating documentation from source files. Supports both command-line and programmatic usage with extensive configuration options.

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

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;
}

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

Core Documentation Generation

Command Line Interface

Comprehensive CLI with extensive configuration options for generating documentation from the command line.

// CLI Options
interface CliOptions {
  input: string[];
  output: string;
  config?: string;
  template?: string;
  verbose?: boolean;
  debug?: boolean;
  quiet?: boolean;
  single?: boolean;
  dryRun?: boolean;
  private?: boolean;
  watch?: boolean;
  markdown?: boolean | string;
  encoding?: string;
  lineEnding?: string;
  fileFilters?: string[];
  excludeFilters?: string[];
  parseFilters?: string[];
  parseLanguages?: string[];
  parseParsers?: string[];
  parseWorkers?: string[];
  definitions?: boolean;
  filterBy?: string;
  logFormat?: 'simple' | 'json';
  warnError?: boolean;
  writeJson?: boolean;
  color?: boolean;
}

Command Line Interface

Internal Architecture

Internal parsing system and architecture details. These are implementation details not exposed through the public API but helpful for understanding the system.

// Internal functions - NOT part of public API
function parse(options): boolean | ApiDocResult;
function parseSource(source: string, options): ParsedElement[];
function getSpecificationVersion(): string;

Internal Architecture

Configuration Management

Configuration file handling and option processing. Supports multiple configuration sources and format validation.

class Reader {
  constructor(app: App);
  read(): ConfigurationData;
  search(): ConfigurationData;
  getHeaderFooter(config: ConfigurationData): HeaderFooterData;
}

interface ConfigurationData {
  name?: string;
  version?: string;
  description?: string;
  title?: string;
  url?: string;
  sampleUrl?: string;
  input?: string[];
  output?: string;
  template?: TemplateOptions;
  header?: HeaderFooterConfig;
  footer?: HeaderFooterConfig;
  order?: string[];
}

interface HeaderFooterConfig {
  title: string;
  filename: string;
}

interface TemplateOptions {
  showRequiredLabels?: boolean;
  withCompare?: boolean;
  withGenerator?: boolean;
  aloneDisplay?: boolean;
}

Configuration Management

HTML Output Generation

Template processing and asset bundling for generating the final HTML documentation. Supports both multi-file and single-file output formats.

class Writer {
  constructor(api: ApiDocResult, app: App, cacheBustingQueryParam?: string);
  write(): Promise<string>;
  createOutputFiles(): Promise<string>;
  createSingleFile(): Promise<void>;
}

HTML Output Generation

Comment Tag System

Complete reference for all supported API documentation tags that can be used in source code comments to generate documentation.

// Core tags
@api {method} path [title]
@apiName name
@apiGroup group
@apiVersion version
@apiDescription text

// Parameter tags  
@apiParam [(group)] [{type}] [field=defaultValue] [description]
@apiQuery [(group)] [{type}] [field=defaultValue] [description]
@apiBody [(group)] [{type}] [field=defaultValue] [description]
@apiHeader [(group)] [{type}] [field=defaultValue] [description]

// Response tags
@apiSuccess [(group)] [{type}] field [description]
@apiError [(group)] [{type}] field [description]

// Example tags
@apiExample {type} title
@apiParamExample {type} title
@apiHeaderExample {type} title
@apiSuccessExample {type} title
@apiErrorExample {type} title

// Control tags
@apiPermission name
@apiPrivate
@apiDeprecated [text]
@apiSampleRequest url|off
@apiUse name
@apiDefine name [title]

Comment Tag System

Plugin System

Extension points for custom parsers, workers, filters, and language support. Allows customization of the documentation generation process.

interface App {
  addHook(name: string, func: Function, priority?: number): void;
  hook(name: string, ...args: any[]): any;
  filters: Record<string, string>;
  languages: Record<string, string>;
  parsers: Record<string, string>;
  workers: Record<string, string>;
}

Plugin System