or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdconfiguration.mdenvironment.mdindex.mdparser.mdplugins.mdtemplates.mdutilities.md
tile.json

tessl/npm-jsdoc

API documentation generator for JavaScript that parses source code and JSDoc comments to produce HTML documentation

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/jsdoc@4.0.x

To install, run

npx @tessl/cli install tessl/npm-jsdoc@4.0.0

index.mddocs/

JSDoc

JSDoc is a comprehensive API documentation generator for JavaScript that parses source code and JSDoc comments to produce HTML documentation. It supports modern JavaScript features through Babel parser integration, provides flexible templating systems for customizing documentation output, and includes extensive plugin architecture for extending functionality.

Package Information

  • Package Name: jsdoc
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install -g jsdoc or npm install --save-dev jsdoc

Core Imports

JSDoc provides a custom require system that allows importing from the lib/jsdoc/ directory using the jsdoc/ prefix:

// Environment and configuration
const env = require('jsdoc/env');
const Config = require('jsdoc/config');

// Parser and AST processing
const parser = require('jsdoc/src/parser');
const astnode = require('jsdoc/src/astnode');
const syntax = require('jsdoc/src/syntax');

// Doclet processing
const doclet = require('jsdoc/doclet');
const name = require('jsdoc/name');

// Utilities
const logger = require('jsdoc/util/logger');
const templateHelper = require('jsdoc/util/templateHelper');

The custom require system is set up by the main jsdoc.js entry point and allows access to all internal modules.

Basic Usage

Command Line Usage

# Generate documentation for a single file
jsdoc myfile.js

# Generate documentation with configuration
jsdoc -c conf.json src/**/*.js

# Generate documentation with custom template
jsdoc -t templates/custom src/**/*.js -d output/

Programmatic Usage

const parser = require('jsdoc/src/parser');
const env = require('jsdoc/env');

// Set up environment
env.opts = { encoding: 'utf8' };
env.conf = { source: { includePattern: '\\.js$' } };

// Create parser and parse files
const jsdocParser = parser.createParser();
const doclets = jsdocParser.parse(['myfile.js']);

console.log('Generated', doclets.length, 'doclets');

Architecture

JSDoc is built around several key components:

  • Command-Line Interface: Primary user interface with extensive configuration options
  • Parser Engine: JavaScript AST parsing with JSDoc comment extraction and doclet generation
  • Plugin System: Extensible architecture for custom tags, handlers, and processing
  • Template System: Flexible HTML generation with customizable themes and layouts
  • Configuration System: JSON-based configuration with environment and CLI option support

Capabilities

Command-Line Interface

Complete command-line tool for generating documentation from JavaScript source files. Supports recursive directory scanning, flexible configuration, and multiple output formats.

# Primary command interface
jsdoc [options] <source files>

# Examples
jsdoc src/**/*.js --destination docs/
jsdoc -c jsdoc.conf.json src/
jsdoc --help

Note: The CLI module is internal and not designed for programmatic use. For programmatic access, use the core modules directly.

Command-Line Interface

JavaScript Parser

Core parsing engine that analyzes JavaScript source code, extracts JSDoc comments, and generates documentation objects (doclets). Supports modern ES6+ syntax and provides event-driven processing.

const parser = {
  createParser(type?: string): Parser;
  PARSERS: { js: string };
}

class Parser {
  constructor(builderInstance?, visitorInstance?, walkerInstance?);
  parse(sourceFiles: string[], encoding?: string): Doclet[];
  addResult(doclet: Doclet): void;
  addAstNodeVisitor(visitor: Function): void;
  clear(): void;
}

JavaScript Parser

Plugin System

Extensible plugin architecture allowing custom JSDoc tags, event handlers, and AST node visitors. Includes built-in plugins for common tasks like Markdown processing and template customization.

const plugins = {
  installPlugins(plugins: string[], parser: Parser): void;
}

// Plugin interface
interface Plugin {
  handlers?: { [eventName: string]: Function };
  defineTags?(dictionary: TagDictionary): void;
  astNodeVisitor?: Function;
}

Plugin System

Template System

Flexible template engine for generating HTML documentation. Supports custom templates, layouts, and helper functions with complete control over output formatting.

class Template {
  constructor(filepath: string);
  load(file: string): Function;
  partial(file: string, data: object): string;
  render(file: string, data: object): string;
}

// Template publish function interface
function publish(data: TaffyDB, opts: object): void;

Template System

Configuration Management

JSON-based configuration system with support for source patterns, plugin loading, template selection, and output customization.

class Config {
  constructor(jsonOrObject?: string | object);
  get(): ConfigObject;
}

interface ConfigObject {
  plugins: string[];
  recurseDepth: number;
  source: {
    includePattern: string;
    excludePattern: string;
  };
  sourceType: string;
  tags: {
    allowUnknownTags: boolean;
    dictionaries: string[];
  };
  templates: {
    monospaceLinks: boolean;
    cleverLinks: boolean;
  };
}

Configuration

Environment and Runtime

Environment management providing access to command-line options, configuration data, version information, and runtime state.

const env = {
  run: { start: Date; finish: Date | null };
  args: any[];
  conf: object;
  dirname: string;
  pwd: string;
  opts: object;
  sourceFiles: string[];
  version: { number: string; revision: string };
}

Environment and Runtime

Utilities

Comprehensive utility modules for logging, data manipulation, debugging, template helpers, and common operations used throughout JSDoc.

// Logging system
const logger = {
  LEVELS: { TRACE: 10; DEBUG: 20; INFO: 30; WARN: 40; ERROR: 50; FATAL: 60; };
  setLevel(level: number | string): void;
  trace(message: string, ...args: any[]): void;
  debug(message: string, ...args: any[]): void;
  info(message: string, ...args: any[]): void;
  warn(message: string, ...args: any[]): void;
  error(message: string, ...args: any[]): void;
  fatal(message: string, ...args: any[]): void;
}

// Template helpers
const templateHelper = {
  longnameToUrl(longname: string): string;
  linkto(longname: string, linkText?: string): string;
  htmlsafe(str: string): string;
  find(spec: object): Doclet[];
  getSignature(doclet: Doclet): string;
}

// Deep object operations
function doop(original: object, extra?: object): object;

// Debug output
function dump(objects: any[]): string;

Utilities

Types

// Core doclet interface
interface Doclet {
  kind: string;
  name: string;
  longname: string;
  description?: string;
  memberof?: string;
  scope?: string;
  meta: {
    path: string;
    filename: string;
    lineno: number;
    code: object;
  };
  // Additional properties based on doclet type
}

// Parser interface
interface Parser {
  parse(sourceFiles: string[], encoding?: string): Doclet[];
  addResult(doclet: Doclet): void;
  addAstNodeVisitor(visitor: Function): void;
  fireProcessingComplete(doclets: Doclet[]): void;
  clear(): void;
}

// AST Node interface  
interface ASTNode {
  type: string;
  nodeId?: string;
  parent?: ASTNode;
  enclosingScope?: ASTNode;
  [key: string]: any;
}

// TaffyDB database interface
interface TaffyDB {
  (): any;
  (query?: object): any;
  get(): any[];
  [key: string]: any;
}

// JSDoc options passed to templates
interface JSDocOptions {
  destination: string;
  encoding: string;
  template: string;
  readme?: string;
  package?: object;
  access?: string[];
  private?: boolean;
  query?: object;
  [key: string]: any;
}

// Tutorial system interfaces
interface TutorialRoot {
  title: string;
  children: Tutorial[];
}

interface Tutorial {
  title: string;
  name: string;
  content: string;
  children?: Tutorial[];
}

// Tag dictionary interface
interface TagDictionary {
  defineTag(name: string, options: object): void;
  [key: string]: any;
}

// Function parameter interface
interface Parameter {
  name: string;
  type?: { names: string[] };
  description?: string; 
  optional?: boolean;
  defaultvalue?: any;
}

// Return value interface  
interface Return {
  type?: { names: string[] };
  description?: string;
}

// Command-line options interface
interface CommandLineOptions {
  destination?: string;
  encoding?: string;
  access?: string[];
  configure?: string;
  debug?: boolean;
  help?: boolean;
  package?: string;
  pedantic?: boolean;
  private?: boolean;
  readme?: string;
  recurse?: boolean;
  template?: string;
  tutorials?: string;
  verbose?: boolean;
  version?: boolean;
  _?: string[];
}