Development

This page is a work in progress overview of TypeDoc's architecture. For more details about each individual component, refer to the doc comments within each module. It is intended primarily for those interested in contributing to the TypeDoc codebase or developing a plugin.

High Level

TypeDoc follows several high level steps when called.

1. Read options - Necessary to determine which plugins should be loaded.
2. Load plugins
3. Read options again to pick up plugin options
4. Convert the input files into the models (also called reflections) that live under src/lib/models
5. Resolve the models
   Necessary to handle links to models that might not have been created when the source model is generated.
6. Output the models by serializing to HTML and/or JSON

TypeDoc's code is loosely organized according to each of these steps. The code to read options lives under src/lib/utils/options. The plugin loading code lives in src/lib/utils/plugins. Conversion is performed according to the Symbol's ts.SymbolFlags. Each distinct flag type gets its own converter function in src/lib/converter/symbols.ts. Resolution is implemented entirely by internal plugins that live in src/lib/output/plugins and listen to the Converter.EVENT_RESOLVE event. Output is split into two folders, for JSON output see the src/lib/serialization directory, and for HTML output see src/lib/output.

Plugins may effect any part of the process after step 2 by listening to events fired by each component or adding / replacing handlers for a given task. As an example, the Converter fires events before starting conversion, when declarations are converted and when the project should be resolved.

Tests

TypeDoc has tests for individual utilities and some components, but the majority of the project is tested by converting source files into their JSON model and comparing it to a known good version. The basic example under src/test/renderer/testProject is rendered to HTML to test theme changes.

If changing the behavior of a converter or resolver, it should be possible to modify one of the existing tests under src/test/converter. Bug fixes or feature additions which need to change one of the specs*.json files should run npm run rebuild_specs [converter|renderer] [converter filter] to run the current build of TypeDoc on the source files and generate new specs. For other components, we use Mocha to write tests.

Running the Visual Regression Tests

When making changes to the themes, it is useful to be able to compare screenshots from the new/old runs.

1. Run node scripts/visual_regression.js
2. Make the UI change
3. Run node scripts/visual_regression.js

The visual regression script accepts several arguments to control what it does, run it with --help to see a summary of the available options.

Components

For more detailed information about the implementation and API surface of each component, consult its API documentation. All components are available on the Application class, which is passed to plugins.

Options

TypeDoc provides some 30 options which determine how the project model is generated and output to disk. The Options class consolidates application options into a single location and handles type conversion.

There are 11 builtin option types as specified by the ParameterType enum.

• String - A string
• Path - A string which will be resolved to a path. Paths in config files will be resolved relative to the config directory.
• Number - A number which is not NaN
• Boolean - true or false
• Map - Defines a map between string keys and an arbitrary type. See the tests for an example.
• Mixed - An object type that is passed through by TypeDoc to create specific implicit behavior.
• Object - An object type of which value keys can be overridden or extended by passing a new object.
• Array - An array of strings.
• PathArray - An array of paths, if specified in a config file, will be resolved relative to the config file directory.
• ModuleArray - An array of modules/paths. Items will be resolved if they start with ..
• GlobArray - An array of globs. Globs will be resolved if they do not start with **, after skipping leading ! and # characters.

Options are discovered and set by option readers, which are documented in the Configuration.OptionsReader interface.

Plugins can declare their own options by calling Options.addDeclaration

Plugins

Plugins should export a load function which will be called by TypeDoc when loading the plugin with an instance of PluginHost. This function should add any options the plugin accepts and add any listeners necessary to effect TypeDoc's behavior.

import { Application, ParameterType, Converter, Context } from "typedoc";

export function load(app: Application) {
    app.options.addDeclaration({
        name: "plugin-option",
        help: "Displayed when --help is passed",
        type: ParameterType.String, // The default
        defaultValue: "", // The default
    });

    app.converter.on(Converter.EVENT_RESOLVE, (context: Context) => {
        if (app.options.getValue("plugin-option") === "something") {
            // ...
        }
    });
}
Copy

Converters

TypeDoc converts the syntax tree created by TypeScript into its own structure of Reflections to allow themes and serialization to work with a standard object format. Conversion is done primarily in three files.

• symbols.ts - contains converters for each ts.Symbol that is exported from entry points.
• types.ts - contains converters for ts.Types and ts.TypeNodes.
• jsdoc.ts - contains converters for types and symbols declared within JSDoc comments.

JSON Output

TypeDoc can produce JSON output which can be consumed by other tools. The format of this JSON is defined by the JSONOutput.ProjectReflection interface. If plugins want to cause custom properties to be included in the output JSON, they can achieve this by adding a serializer to Serializer. If custom properties are added, they should generally also be revived with a Deserializer so that they can be used with TypeDoc's packages mode.

HTML Output

See Custom Themes for creating a theme.