TypeDoc plugins overview

Overview

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

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

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.

• Hierarchy fixer — typeDocHierarchyFixer()

  The plugin restores the class hierarchy broken by extending an intermediate mixin constant, e.g. const ClassicEditorBase = ElementApiMixin( Editor ). It replaces the unresolvable base class reference with the actual base class, restores the "Subclasses" relation on the base class, and lists the mixin interfaces as implemented by the extending class. It also removes references pointing to reflections purged from private packages.

  The plugin must be executed after typeDocEventInheritanceFixer(), because inheriting events resolves the original (broken) references replaced by this plugin.

• 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.

• Restore program after conversion — typeDocRestoreProgramAfterConversion()

  The plugin restores the TypeScript program used for the source conversion. TypeDoc deletes the context.program property once the conversion is finished, which prevents other plugins listening to the EVENT_END event from using the TypeScript API.

• Reference fixer — typeDocReferenceFixer()

  The plugin fixes reflections that are re-exported from another file as a default export. In such a case TypeDoc adds the reflection declaration to the file containing the re-export, while the actual source file contains only a reference. The plugin moves the declarations back to their source locations.

• Output clean-up — typeDocOutputCleanUp()

  The plugin removes unnecessary properties from reflections to decrease the size of the generated output.

• Validators — validate()

  Validates the CKEditor 5 documentation. It verifies the @see and @link references and the events specified in the @fires annotation. Optionally, when the enableOverloadValidator option is enabled, it also verifies whether overloaded signatures use the @label annotation.

Changelog

See the CHANGELOG.md file.