TypeDoc plugins overview

Overview

This repository consists of a few plugins which extend the capabilities of TypeDoc.

[!WARNING] The @ckeditor/typedoc-plugins requires typedoc@0.28.

Before enabling plugins from the package, you need to install it first.

npm install @ckeditor/typedoc-plugins

Below you can find the detailed overview of available plugins.

Usage

To use the typedoc-plugins, you need to create an instance of the Typedoc application.

import { Application } from 'typedoc';
import { typeDocSymbolFixer } from '@ckeditor/typedoc-plugins';

const app = await Application.bootstrapWithPlugins( { /* Typedoc options. */ } );

// It is essential to execute a plugin before converting the project.
typeDocSymbolFixer( app );

const conversionResult = await typeDoc.convert();

Available plugins

• Module fixer — typeDocModuleFixer()

  The plugin reads the module name specified in the @module annotation.

  import type { TypeDefinition } from '...';
  
  /**
   * @module package/file
   */

  For the example specified above, the name of the parsed module should be equal to package/file.

  The import statements may be specified above the "@module" block code. In such a case, the default module parser from typedoc returns the module name based on a path relative to the project root.

• Symbol fixer — typeDocSymbolFixer()

  The plugin renames Symbol.* definitions with the JSDoc style.

  • Typedoc: [iterator]() → Iterator
  • JSDoc: Symbol.iterator() → Iterator

• Interface augmentation fixer — typeDocInterfaceAugmentationFixer()

  The plugin tries to fix an interface, that has been extended (augmented) from the outside (from another module) in the re-exported index.ts file. When the extending "declare module ..." declaration contains the full package name, it points to the index.ts file instead of the actual source file. The goal is to add missing properties from interfaces to their source locations.

• Event parameter fixer — typeDocEventParamFixer()

  The plugin injects the eventInfo parameter (an instance of the EventInfo class) as the first parameter for each event reflection.

• Events inheritance fixer — typeDocEventInheritanceFixer()

  The plugin takes care of inheriting events, which are created manually via the @eventName annotation.

• Purge private API — typeDocPurgePrivateApiDocs()

  The plugin removes reflections collected from private packages (marked as "private": true in their package.json). To disable the mechanism, add the @publicApi annotation at the beginning of a file.

• Tag @error — typeDocTagError()

  The plugin collects error definitions from the @error annotation.

• Tag @eventName — typeDocTagEvent()

  The plugin collects event definitions from the @eventName annotation and assigns them as the children of the class or the Observable interface.

  We are not using the @event annotation, known from the JSDoc specification, because it has a special meaning in the TypeDoc, and it would be difficult to get it to work as we expect.

• Tag @observable — typeDocTagObservable()

  Adds support for creating CKEditor 5 events from properties marked as @observable.

Changelog

See the CHANGELOG.md file.