or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

index.mddocs/

ESDoc Standard Plugin

ESDoc Standard Plugin is a glue plugin for ESDoc that aggregates eleven different ESDoc plugins into a single convenient package. It automatically configures and loads multiple ESDoc plugins including lint, coverage, accessor, type inference, external ECMAScript references, branding, documentation detection, manual integration, test integration, and HTML publishing capabilities.

Package Information

  • Package Name: esdoc-standard-plugin
  • Package Type: npm
  • Language: JavaScript (CommonJS)
  • Installation: npm install esdoc-standard-plugin

Core Imports

const plugin = require("esdoc-standard-plugin");

Basic Usage

// ESDoc configuration file (.esdoc.json)
{
  "source": "./src",
  "destination": "./doc", 
  "plugins": [
    {
      "name": "esdoc-standard-plugin",
      "option": {
        "lint": {"enable": true},
        "coverage": {"enable": true},
        "accessor": {"access": ["public", "protected", "private"], "autoPrivate": true},
        "undocumentIdentifier": {"enable": true},
        "unexportedIdentifier": {"enable": false},
        "typeInference": {"enable": true},
        "brand": {
          "title": "My Library",
          "description": "this is awesome library"
        },
        "manual": {
          "files": ["./manual/overview.md"]
        },
        "test": {
          "source": "./test/",
          "interfaces": ["describe", "it", "context", "suite", "test"],
          "includes": ["(spec|Spec|test|Test)\\.js$"]
        }
      }
    }
  ]
}

Architecture

ESDoc Standard Plugin operates as a glue plugin in the ESDoc ecosystem:

  • Plugin Architecture: Implements ESDoc's plugin interface with event handlers
  • Automatic Aggregation: Dynamically loads constituent plugins during ESDoc initialization
  • Configuration Passthrough: Routes option properties to corresponding constituent plugins
  • Duplicate Prevention: Checks for existing plugins to avoid conflicts

Capabilities

Plugin Event Handler

Main entry point that handles the ESDoc plugin loading process.

/**
 * Event handler that dynamically adds constituent plugins to the ESDoc processing pipeline
 * @param {Object} ev - Event object from ESDoc
 * @param {Object} ev.data - Event data containing plugin information
 * @param {Array} ev.data.plugins - Array of existing plugins
 * @param {Object} [ev.data.option] - Configuration options for various plugins
 */
onHandlePlugins(ev);

Event Object Structure:

interface PluginEvent {
  data: {
    plugins: Array<PluginDefinition>;
    option?: PluginOptions;
  };
}

interface PluginDefinition {
  name: string;
  option?: Object;
}

Configuration Options

The plugin accepts a configuration object with options for each constituent plugin:

interface PluginOptions {
  /** Options for esdoc-lint-plugin */
  lint?: {
    enable?: boolean;
  };
  
  /** Options for esdoc-coverage-plugin */
  coverage?: {
    enable?: boolean;
  };
  
  /** Options for esdoc-accessor-plugin */
  accessor?: {
    access?: Array<"public" | "protected" | "private">;
    autoPrivate?: boolean;
  };
  
  /** Options for esdoc-type-inference-plugin */
  typeInference?: {
    enable?: boolean;
  };
  
  /** Options for esdoc-brand-plugin */
  brand?: {
    logo?: string;
    title?: string;
    description?: string;
    repository?: string;
    site?: string;
    author?: string;
    image?: string;
  };
  
  /** Options for esdoc-undocumented-identifier-plugin */
  undocumentIdentifier?: {
    enable?: boolean;
  };
  
  /** Options for esdoc-unexported-identifier-plugin */
  unexportedIdentifier?: {
    enable?: boolean;
  };
  
  /** Options for esdoc-integrate-manual-plugin */
  manual?: {
    index?: string;
    globalIndex?: boolean;
    asset?: string;
    files?: Array<string>;
  };
  
  /** Options for esdoc-integrate-test-plugin */
  test?: {
    source?: string;
    interfaces?: Array<string>;
    includes?: Array<string>;
    excludes?: Array<string>;
  };
}

Constituent Plugins

The standard plugin automatically loads these ESDoc plugins:

  1. esdoc-lint-plugin - Code linting and style checking
  2. esdoc-coverage-plugin - Documentation coverage analysis
  3. esdoc-accessor-plugin - Access modifier processing
  4. esdoc-type-inference-plugin - Automatic type inference
  5. esdoc-external-ecmascript-plugin - External ECMAScript references
  6. esdoc-brand-plugin - Documentation branding and customization
  7. esdoc-undocumented-identifier-plugin - Detection of undocumented identifiers
  8. esdoc-unexported-identifier-plugin - Detection of unexported identifiers
  9. esdoc-integrate-manual-plugin - Manual documentation integration
  10. esdoc-integrate-test-plugin - Test file integration
  11. esdoc-publish-html-plugin - HTML output generation

Module Export

/**
 * The plugin instance exported as the default export
 * @type {Plugin}
 */
module.exports = pluginInstance;

The plugin exports a single instance of the Plugin class, ready to be used by ESDoc.

Plugin Class

/**
 * Main plugin class that handles ESDoc plugin aggregation
 */
class Plugin {
  /**
   * Event handler called during ESDoc plugin initialization
   * Dynamically adds constituent plugins to the processing pipeline
   * @param {PluginEvent} ev - Event object containing plugin data
   */
  onHandlePlugins(ev);
}

Usage Examples

Minimal Configuration

// .esdoc.json
{
  "source": "./src",
  "destination": "./doc",
  "plugins": [
    {"name": "esdoc-standard-plugin"}
  ]
}

Full Configuration

// .esdoc.json
{
  "source": "./src",
  "destination": "./doc",
  "plugins": [
    {
      "name": "esdoc-standard-plugin",
      "option": {
        "lint": {"enable": true},
        "coverage": {"enable": true},
        "accessor": {
          "access": ["public", "protected", "private"],
          "autoPrivate": true
        },
        "undocumentIdentifier": {"enable": true},
        "unexportedIdentifier": {"enable": false},
        "typeInference": {"enable": true},
        "brand": {
          "logo": "./logo.png",
          "title": "My Library",
          "description": "this is awesome library",
          "repository": "https://github.com/foo/bar",
          "site": "http://my-library.org",
          "author": "https://twitter.com/foo",
          "image": "http://my-library.org/logo.png"
        },
        "manual": {
          "index": "./manual/index.md",
          "globalIndex": true,
          "asset": "./manual/asset",
          "files": [
            "./manual/overview.md",
            "./manual/design.md",
            "./manual/installation.md",
            "./manual/usage1.md",
            "./manual/usage2.md",
            "./manual/tutorial.md",
            "./manual/configuration.md",
            "./manual/example.md",
            "./manual/advanced.md",
            "./manual/faq.md",
            "./CHANGELOG.md"
          ]
        },
        "test": {
          "source": "./test/",
          "interfaces": ["describe", "it", "context", "suite", "test"],
          "includes": ["(spec|Spec|test|Test)\\.js$"],
          "excludes": ["\\.config\\.js$"]
        }
      }
    }
  ]
}