API Documentation Generator

Common errors

• apidoc: command not found

  cause The `apidoc` CLI tool is not installed globally on your system, or its installation path is not included in your system's PATH environment variable.
  fix Install apidoc globally: `npm install -g apidoc` or `yarn global add apidoc`. Verify your npm/yarn global bin directory is correctly set up in your shell's PATH.

• Error: Node.js v14 is not supported. Please upgrade to v16 or higher.

  cause You are attempting to run apidoc v1.0.0 or later with an unsupported Node.js version, which is now a hard requirement.
  fix Upgrade your Node.js version to 16 or higher. For example, using nvm: `nvm install 16 && nvm use 16`.

• TypeError: Cannot read properties of undefined (reading 'data') or 'project'

  cause When using `createDoc` programmatically, the function returned `true` (indicating an error occurred) instead of the expected documentation object, often due to parsing issues or misconfiguration.
  fix Always check if `typeof docResult !== 'boolean'` after calling `createDoc`. If it's `true`, an error occurred. Ensure `silent: false` in your configuration to see console errors, and verify your `src` directory exists and contains valid `@api` comments.

• The generated API documentation HTML bundle is empty or contains only boilerplate, despite source files having comments.

  cause This can happen if input files are incorrectly filtered, if no valid `@api` comments are found, or in very old versions, due to a bug where the bundle wasn't written.
  fix Double-check your `--input` (or `src`) paths and ensure `--exclude` (or `excludeFilters`) options are not overly restrictive. Verify your source files contain correctly formatted `@api` comments. If on an older apidoc version, upgrading to v1.0.0+ resolves a known bundle generation bug.

Warnings

• breaking Starting with apidoc v1.0.0, Node.js v16 or newer is explicitly required. Running on older Node.js versions (e.g., v14) will result in execution errors.
  Fix: Upgrade your Node.js environment to version 16 or higher. Tools like `nvm` or `volta` can help manage multiple Node.js versions.
• gotcha Prior to apidoc v1.0.0, there was a known issue where the documentation bundle might not be generated into the output directory unless the tool was run with the `--debug` flag. This could lead to seemingly successful runs with empty documentation folders.
  Fix: Upgrade to apidoc v1.0.0 or higher. If upgrading is not immediately possible, try running the CLI with `apidoc -i src/ -o doc/ --debug`.
• gotcha Older versions of apidoc (pre-1.0.2) experienced issues with group names containing non-Latin characters or parentheses, which could cause rendering problems, specifically affecting scrollspy navigation.
  Fix: Ensure you are using apidoc v1.0.2 or newer. If issues persist, consider simplifying `@apiGroup` names to alphanumeric characters and hyphens.
• gotcha Incorrectly formatted or incomplete JSDoc-style `@api` comments can lead to silent failures, partial documentation, or parsing errors during generation. This is especially common with complex `@apiParam` or `@apiSuccessExample` blocks.
  Fix: Thoroughly review your `@api` comment syntax against the official apidocjs.com documentation. Use the `dryRun: true` option in programmatic usage or the `--debug` flag in CLI mode to get more detailed parsing output and identify syntax errors.

Install

• npm install apidoc npm
• yarn add apidoc yarn
• pnpm add apidoc pnpm

Imports

• createDoc
  wrong:

  const { createDoc } = require('apidoc')

  correct:

  import { createDoc } from 'apidoc'

  apidoc primarily supports ESM for programmatic usage; using CommonJS `require` might lead to import errors or require specific transpilation setups in modern Node.js environments.
• apidoc CLI
  wrong:

  node apidoc -i src/ -o doc/

  correct:

  apidoc -i src/ -o doc/

  The `apidoc` command is typically executed directly after global installation (`npm install -g apidoc`). Invoking it via `node apidoc` is not the standard or recommended approach for the CLI tool.
• ApidocReturn type

  import { createDoc, ApidocReturn } from 'apidoc'

  For TypeScript users, importing `ApidocReturn` or similar types (available via `@types/apidoc` or bundled types) provides type safety for the object returned by `createDoc` (which contains `data` and `project` properties).

Quickstart

Demonstrates programmatic API documentation generation using `createDoc`, illustrating how to specify source/destination paths, control output, and access the parsed documentation data and project information.

import path from 'path';
import { createDoc } from 'apidoc';

// Resolve paths relative to the current script execution
const projectRoot = path.resolve(__dirname, '..'); 
// Using 'example' folder from a cloned apidoc repository for demonstration
const srcPath = path.resolve(projectRoot, 'example'); 
const destPath = path.resolve(projectRoot, 'docs');

console.log(`Attempting to generate API documentation from: ${srcPath} to: ${destPath}`);

const docResult = createDoc({
  src: srcPath,
  dest: destPath,
  // Set dryRun to true to parse and return data without writing files to disk
  dryRun: false,
  // Set silent to true to suppress apidoc's console output during generation
  silent: false,
  // Optional: Define custom parsing options or template paths here
});

if (typeof docResult !== 'boolean') {
  console.log('API documentation generated successfully!');
  console.log('Parsed API definitions count:', docResult.data.length);
  console.log('Project information:', docResult.project.name, docResult.project.version);
} else {
  console.error('Failed to generate API documentation. Check logs for detailed errors and ensure source paths are correct and comments are well-formed.');
}