tessl/npm-jsdoc

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Command-Line Interface

Name: tessl/npm-jsdoc
Author: tessl

JSDoc's command-line interface provides comprehensive control over documentation generation through the main jsdoc command and its options. The CLI module is internal and not intended for programmatic use.

Capabilities

Command Execution

The JSDoc CLI is primarily designed for command-line usage rather than programmatic access.

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

Important Note: The CLI module (cli.js) is marked as private and is not designed for external programmatic use. For programmatic access to JSDoc functionality, use the core modules directly:

// Programmatic usage - use core modules instead of CLI
const parser = require('jsdoc/src/parser');
const env = require('jsdoc/env');
const Config = require('jsdoc/config');

Internal Implementation

The CLI module contains internal functions that handle the documentation generation workflow, but these are not part of the public API. External users should use the command-line interface or the core modules for programmatic access.

Command-Line Options

Basic Options

# Help and version
jsdoc --help                    # Display help message
jsdoc --version                 # Display version information

# Input and output
jsdoc file1.js file2.js         # Process specific files
jsdoc --destination ./docs      # Output directory (default: ./out/)
jsdoc --recurse                 # Recurse into subdirectories

Configuration Options

# Configuration file
jsdoc --configure conf.json     # Use custom configuration file
jsdoc --encoding utf8           # File encoding (default: utf8)

# Package and README
jsdoc --package package.json    # Package file path
jsdoc --readme README.md        # README file path

Template and Plugin Options

# Template selection
jsdoc --template ./my-template  # Custom template directory

# Access control
jsdoc --access public           # Show only public symbols
jsdoc --private                 # Include private symbols

Debug and Logging Options

# Debugging
jsdoc --debug                   # Enable debug logging
jsdoc --verbose                 # Enable verbose logging
jsdoc --pedantic                # Treat warnings as errors
jsdoc --explain                 # Dump doclet internals

Testing Options

# Testing
jsdoc --test                    # Run test suite
jsdoc --match pattern           # Filter tests by pattern
jsdoc --nocolor                 # Disable colored output

Usage Examples

Basic Documentation Generation

# Single file
jsdoc mylib.js

# Multiple files
jsdoc src/core.js src/utils.js src/api.js 

# Directory with recursion
jsdoc --recurse src/

# Custom output directory
jsdoc --recurse src/ --destination docs/

Advanced Configuration

# With configuration file
jsdoc --configure jsdoc.conf.json src/

# With custom template
jsdoc --template templates/custom src/ --destination public/docs/

# Include private members
jsdoc --private --access all src/

Development and Debugging

# Debug mode with verbose output
jsdoc --debug --verbose src/

# Dump internal doclet data
jsdoc --explain src/core.js

# Run tests
jsdoc --test

Integration Patterns

Package.json Scripts

{
  "scripts": {
    "docs": "jsdoc --configure jsdoc.conf.json --destination docs/ src/",
    "docs:watch": "nodemon --exec 'npm run docs' --watch src/",
    "docs:serve": "npm run docs && http-server docs/"
  }
}

Build Tool Integration

// Gulp integration
const { spawn } = require('child_process');

function generateDocs() {
  return spawn('jsdoc', [
    '--configure', 'jsdoc.conf.json',
    '--destination', 'dist/docs/',
    'src/'
  ], { stdio: 'inherit' });
}

CI/CD Pipeline

# GitHub Actions example
- name: Generate Documentation
  run: |
    npm install -g jsdoc
    jsdoc --configure jsdoc.conf.json --destination docs/ src/
    
- name: Deploy Documentation
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./docs

Error Handling

Common Exit Codes

0: Success
1: General error (parsing, configuration, or generation failure)

Error Categories

Configuration Errors: Invalid config file, missing template
Parsing Errors: Syntax errors in source files, invalid JSDoc comments
Generation Errors: Template errors, file system issues
Plugin Errors: Plugin loading failures, plugin execution errors

Debug Techniques

# Enable debug logging
jsdoc --debug --verbose src/

# Dump doclet internals
jsdoc --explain src/problematic-file.js

# Pedantic mode (warnings as errors)
jsdoc --pedantic src/