@ckeditor/typedoc-plugins
Version:
Various TypeDoc plugins developed by the CKEditor 5 team.
97 lines (55 loc) • 4.06 kB
Markdown
# TypeDoc plugins overview
[](https://www.npmjs.com/package/@ckeditor/typedoc-plugins)
[](https://app.circleci.com/pipelines/github/ckeditor/ckeditor5-dev?branch=master)
## Overview
This repository consists of a few plugins which extend the capabilities of [TypeDoc](https://typedoc.org/).
> [!WARNING]
> The [`@ckeditor/typedoc-plugins`](https://www.npmjs.com/package/@ckeditor/typedoc-plugins) requires [`typedoc@0.28`](https://npmjs.com/package/typedoc).
Before enabling plugins from the package, you need to install it first.
```bash
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.
```js
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.
```ts
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`](#tag-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`](https://typedoc.org/tags/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`](https://github.com/ckeditor/ckeditor5-dev/blob/master/packages/typedoc-plugins/CHANGELOG.md) file.