Utilities to parse type information and JSDoc annotations from TypeScript source files, and render Markdown documentation
First:
$ npm install --save-dev generate-ts-docs
Suppose that we have the following (highly contrived) toy example.ts
source file:
/**
* Adds two numbers.
*
* @param x First number to add.
* @param y Second number to add.
* @return The sum of `x` and `y`.
*/
export function add(x: number, y: number): number {
return x + y
}
…and the following generate-ts-docs.ts
script:
import {
parseExportedFunctionsAsync,
renderFunctionDataToMarkdown
} from 'generate-ts-docs'
async function main() {
const functionsData = await parseExportedFunctionsAsync(['./example.ts'])
for (const functionData of functionsData) {
console.log(renderFunctionDataToMarkdown(functionData))
}
}
main()
parseExportedFunctionsAsync
receives an array of globs of TypeScript source files, and parses the functions in these files that have the export
keyword. It returns an array of FunctionData
objects with the following shape:
[
{
description: 'Adds two numbers.',
name: 'add',
parameters: [
{
description: 'First number to add.',
name: 'x',
optional: false,
type: 'number'
},
{
description: 'Second number to add.',
name: 'y',
optional: false,
type: 'number'
}
],
returnType: { description: 'The sum of `x` and `y`.', type: 'number' },
tags: null
}
]
renderFunctionDataToMarkdown
renders the given array of FunctionData
objects to a Markdown string.
Now, let’s run the generate-ts-docs.ts
script, piping its output to a file:
$ npx ts-node generate-ts-docs.ts > README.md
The output README.md
will be as follows:
# add(x, y)
Adds two numbers.
## *Parameters*
- **`x`** (`number`) – First number to add.
- **`y`** (`number`) – Second number to add.
## *Return type*
The sum of `x` and `y`.
```
number
```
export type FunctionData = {
description: null | string
name: string
parameters: Array<ParameterData>
returnType: null | ReturnTypeData
tags: null | TagsData
}
export type ParameterData = {
description: null | string
name: string
optional: boolean
type: string | ObjectData
}
export type ObjectData = {
keys: Array<ParameterData>
type: 'object'
}
export type ReturnTypeData = {
description: null | string
type: string
}
export type TagsData = { [key: string]: null | string }
Parses the exported functions defined in the given globs
of TypeScript
files.
- Functions with the
@ignore
JSDoc tag will be skipped. - Functions will be sorted in ascending order of their
@weight
JSDoc tag. A function with the@weight
tag will be ranked before a function without the@weight
tag.
globs
(Array<string>
) – One or more globs of TypeScript files.options
(object
) – Optional.tsconfigFilePath
(string
) – Path to a TypeScript configuration file. Defaults to./tsconfig.json
.
Promise<Array<FunctionData>>
Groups each object in functionsData
by the value of each function’s
tags.category
key.
functionsData
(Array<FunctionData>
)
Array<{
name: string;
functionsData: Array<FunctionData>;
}>
category
(object
)name
(string
)functionsData
(Array<FunctionData>
)
options
(object
) – Optional.headerLevel
(number
) – Header level to be used for rendering the category name. Defaults to1
(ie.#
).
string
functionData
(FunctionData
)options
(object
) – Optional.headerLevel
(number
) – Header level to be used for rendering the function name. Defaults to1
(ie.#
).
string
Generate a Markdown table of contents for the given categories
.
categories
(Array<{ name: string; functionsData: Array<FunctionData>; }>
)
string
Generate a Markdown table of contents for the given functionsData
.
functionsData
(Array<FunctionData>
)
string
$ npm install --save-dev generate-ts-docs
The parseExportedFunctionsAsync
function works via the following two-step process:
- Generate type declarations for the given TypeScript source files.
- Traverse and extract relevant information from the AST of the generated type declarations.