JSDoc Configuration

Purpose and Scope

This document describes the JSDoc configuration system used to generate API documentation for the jsjiit library. It explains the structure and settings defined in jsdoc.conf.json1-25 how the configuration is invoked through npm scripts, and how JSDoc processes source files to produce HTML documentation. For information about the automated deployment of generated documentation to GitHub Pages, see Automated Documentation Deployment.

Configuration File Overview

The JSDoc configuration is defined in jsdoc.conf.json1-25 a JSON file that controls all aspects of documentation generation. The file is referenced by the docs npm script defined in package.json14:

"docs": "jsdoc -c jsdoc.conf.json --verbose"

The configuration file is organized into four main sections: source, opts, tags, and templates, each controlling a different aspect of the documentation generation process.

Sources: jsdoc.conf.json1-25 package.json14

Configuration Structure

Diagram: JSDoc Configuration Structure

Sources: jsdoc.conf.json1-25

Source Configuration

The source section jsdoc.conf.json2-13 defines which files JSDoc should process and which to ignore.

Include Patterns

The include array jsdoc.conf.json3-7 explicitly lists directories and files to process:

Exclude Patterns

The exclude array jsdoc.conf.json8-10 prevents processing of specific directories:

File Pattern Matching

Two regular expressions control fine-grained file selection:

includePattern jsdoc.conf.json11:

".+\\.js(doc|x)?$"

This pattern matches:

• .js files (standard JavaScript)
• .jsdoc files (JSDoc-specific files)
• .jsx files (React components, if present)

excludePattern jsdoc.conf.json12:

"(^|\\/|\\\\)_"

This pattern excludes files/directories starting with underscore (_), which conventionally indicates private or internal implementation files.

Sources: jsdoc.conf.json2-13

Output Options

The opts section jsdoc.conf.json14-17 controls where and how documentation is generated:

The destination path jsdoc.conf.json15 is relative to the project root. With recurse: true jsdoc.conf.json16 JSDoc processes all JavaScript files in src/ and its subdirectories, ensuring complete coverage of the codebase.

Sources: jsdoc.conf.json14-17

Tag Processing

The tags section jsdoc.conf.json18-20 configures how JSDoc handles documentation tags:

"tags": {
    "allowUnknownTags": true
}

With allowUnknownTags: true jsdoc.conf.json19 JSDoc does not throw errors when encountering custom or non-standard tags. This flexibility is important for:

• Experimenting with new documentation patterns
• Using custom tags for internal tooling
• Preventing build failures due to unrecognized tags in third-party code

Sources: jsdoc.conf.json18-20

Template Configuration

The templates section jsdoc.conf.json21-24 controls link rendering in generated documentation:

These settings improve documentation readability by:

• Making code references visually distinct from prose
• Ensuring consistent styling of API references across the documentation

Sources: jsdoc.conf.json21-24

JSDoc Execution Flow

Diagram: JSDoc Documentation Generation Pipeline

The process begins when a developer runs npm run docs, which invokes the jsdoc binary with the configuration file package.json14 JSDoc then:

1. Loads Configuration: Parses jsdoc.conf.json1-25 to determine processing rules
2. Scans Sources: Recursively walks src/ directory and reads package.json1-61 and README.md
3. Filters Files: Applies includePattern and excludePattern to select processable files
4. Parses Code: Uses @babel/parser package-lock.json36-51 to generate ASTs
5. Extracts Documentation: Identifies JSDoc comments and processes them
6. Processes Markdown: Uses markdown-it package-lock.json676-693 for Markdown content
7. Generates HTML: Creates documentation in ./docs directory

Sources: package.json14 jsdoc.conf.json1-25 package-lock.json619-648

JSDoc Dependency Tree

The JSDoc tool installed via package.json59 brings a substantial dependency tree that enables its functionality:

Diagram: JSDoc Dependency Graph

Key Dependencies

Sources: package-lock.json619-648 package-lock.json36-51 package-lock.json676-693

Integration with Build System

The JSDoc configuration integrates with the project's npm scripts defined in package.json12-16:

The docs script is not automatically triggered during package publishing. Documentation generation is handled separately by the GitHub Actions workflow described in Automated Documentation Deployment.

The --verbose flag package.json14 provides detailed output during documentation generation, which is useful for:

• Debugging configuration issues
• Identifying files being processed
• Detecting parse errors in JSDoc comments

Sources: package.json12-16

Source File Coverage

Based on the configuration, JSDoc processes the following files:

Diagram: Documentation Source Coverage

All files ending in .js within src/ are processed recursively. The includePattern jsdoc.conf.json11 ensures comprehensive coverage of the codebase, while excludePattern jsdoc.conf.json12 prevents private implementation files (those starting with _) from appearing in public documentation.

Sources: jsdoc.conf.json2-13

Output Structure

The destination: ./docs setting jsdoc.conf.json15 creates the following structure:

./docs/
├── index.html              # Documentation homepage
├── WebPortal.html          # Class documentation
├── WebPortalSession.html   # Class documentation
├── AttendanceHeader.html   # Class documentation
├── Semester.html           # Class documentation
├── RegisteredSubject.html  # Class documentation
├── ExamEvent.html          # Class documentation
├── global.html             # Global functions and constants
├── styles/                 # CSS styling
├── scripts/                # JavaScript for search/navigation
└── fonts/                  # Typography assets

Each source file in src/ with JSDoc comments generates corresponding HTML pages in ./docs The generated documentation is then deployed to GitHub Pages through the workflow described in Automated Documentation Deployment.

Sources: jsdoc.conf.json14-17

Configuration Best Practices

The jsjiit configuration demonstrates several best practices:

1. Explicit Inclusion: Listing src, package.json, and README.md explicitly jsdoc.conf.json3-7 ensures predictable documentation scope
2. Pattern-Based Exclusion: Using regex patterns jsdoc.conf.json11-12 provides flexible file filtering without hardcoding filenames
3. Recursive Processing: Setting recurse: true jsdoc.conf.json16 ensures all subdirectories are processed without manual listing
4. Permissive Tag Handling: Allowing unknown tags jsdoc.conf.json19 prevents build failures while maintaining documentation quality
5. Enhanced Readability: Monospace links jsdoc.conf.json23 improve visual distinction between code and prose

Sources: jsdoc.conf.json1-25

Relationship to GitHub Actions

While this configuration file defines what gets documented and how, the actual documentation generation for each release is automated through GitHub Actions. The workflow:

1. Installs the jsdoc dependency from package.json59
2. Executes npm run docs using this configuration file
3. Deploys the generated ./docs directory to GitHub Pages

This separation allows developers to generate documentation locally for testing using npm run docs, while ensuring consistent, automated documentation deployment for releases. The automation details are covered in Automated Documentation Deployment.

Sources: package.json14 package.json59