https://github.com/socsieng/typedoc-plugin-typescript-declaration
Typedoc plugin to render to typescript declaration file
https://github.com/socsieng/typedoc-plugin-typescript-declaration
plugin typedoc typedocplugin typescript
Last synced: 11 months ago
JSON representation
Typedoc plugin to render to typescript declaration file
- Host: GitHub
- URL: https://github.com/socsieng/typedoc-plugin-typescript-declaration
- Owner: socsieng
- Created: 2020-01-08T18:44:13.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-03-02T11:24:28.000Z (over 3 years ago)
- Last Synced: 2024-04-26T03:02:52.781Z (about 2 years ago)
- Topics: plugin, typedoc, typedocplugin, typescript
- Language: TypeScript
- Homepage:
- Size: 1.97 MB
- Stars: 2
- Watchers: 2
- Forks: 1
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# typedoc-plugin-typescript-declaration
[](https://github.com/socsieng/typedoc-plugin-typescript-declaration/actions?query=workflow%3A%22build%22)
[](https://badge.fury.io/js/typedoc-plugin-typescript-declaration)
This is a Typedoc plugin that renders a TypeScript declaration file.
## Installation
```sh
npm install typedoc typedoc-plugin-typescript-declaration --save-dev
```
## Usage
Used as a plugin with Typedoc:
```sh
# generate Typedoc documentation as well as the type declaration
node_modules/.bin/typedoc --out docs --declarationFile docs/index.d.ts
# generate type declaration file without Typedoc documentation (omit --out, or inclue --declarationOnly)
node_modules/.bin/typedoc --declarationFile docs/index.d.ts
# generate type declaration file for a specific file
# node_modules/.bin/typedoc --declarationFile [file]
node_modules/.bin/typedoc --declarationFile docs/index.d.ts src/index.ts
# write declaration file for types with a max version of 1.0
node_modules/.bin/typedoc --out docs/v1.0 --declarationFile docs/v1.0/index.d.ts --maxVersion 1.0
# write declaration file for types with a max version of 2.0
node_modules/.bin/typedoc --out docs/v2.0 --declarationFile docs/v2.0/index.d.ts --maxVersion 2.0
```
Used as a stand alone cli (works with the same options above):
```sh
# using npx
npx typedoc-plugin-typescript-declaration --declarationFile index.d.ts
# optionally install this package globally
npm install --global typedoc-plugin-typescript-declaration
# generate type declaration file with max version 2.0
node_modules/.bin/typedoc-declare --declarationFile index.d.ts --maxVersion 2.0
# when installed globally
typedoc-declare --declarationFile index.d.ts --maxVersion 2.0
```
## Why?
Reasons for using this plugin:
- You publish and maintain TypeScript definitions
- You have `@internal` or `@hidden` types in your documentation that you would like reflected in your type definitions
- You would like to publish multiple versions of your type definitions from a single source of truth
## Publish multiple versions
You can target multiple versions of the type definitions by using the `@since ` tag and suppliying a maximum version number with `--maxVersion `. Any definitions tagged with a `@since` version greater than the `--maxVersion` will be filtered out.
### Example
Sample file:
```ts
export class MyClass {
originalFunction() {}
/**
* @since 1.0
*/
newFunction() {}
/**
* @since 2.0
*/
newerFunction() {}
}
```
Command:
```sh
# write declaration file for types with a max version of 1.0
node_modules/.bin/typedoc --declarationFile docs/v1.0/index.d.ts --maxVersion 1.0
# write declaration file for types with a max version of 2.0
node_modules/.bin/typedoc --declarationFile docs/v2.0/index.d.ts --maxVersion 2.0
```
## Inlining `keyof` types
You can use this plugin to *@inline* `keyof` types directly into a union to produce a more concise document and `.d.ts` file.
In addition to comments for each of the keys will also be documented as part of the `@inline` type.
### Example
Sample file:
```ts
/**
* @inline
*/
type SwitchState = keyof {
/**
* Switch is on
*/
on: string,
/**
* Switch is off
*/
off: string,
/**
* State of the switch is uknown
*
* @since 2.0
*/
unknown: string,
};
```
Produces the following (with `--maxVersion 1.0`):
```ts
/**
* Options:
*
* - `on`:
* Switch is on
*
* - `off`:
* Switch is off
*/
type SwitchState = "on" | "off";
```