ts-code-api
v0.4.2
Published
[![version](https://img.shields.io/npm/v/ts-code-api.svg)](https://www.npmjs.com/package/ts-code-api) ![license](https://img.shields.io/npm/l/ts-code-api.svg)
Downloads
1
Maintainers
Readme
ts-code-api
Extract function and constants definitions with JSDocs comments from typescript code to a JavaScript object. You can then use this object generate documentations with your favorite template engine.
If you want to output markdown, generate HTML then use converter library (e.g. turndown) to convert them to markdown files.
Installation
npm i -D ts-code-api
Usage
Assuming that you have following typescript code helper.ts
in src
folder:
// @overview: Helper functions for mathematics calculations.
const add = (a: number, b: number) => a + b;
/**
* Sum up a set of numbers
* @param numbers numbers which you want to sum up
* @returns sum of the numbers
*/
export const sum = (a: number, ...numbers: number[]) => numbers.reduce(add, a);
/**
* Some magic number
*/
export const MAGIC_NUMBER: number = 89757;
Using this library:
// your NodeJS script
const { tsDoc } = require('ts-code-api');
const output = tsDoc({
files: ['src/helper.ts'],
});
console.log(output);
The output will be:
[
{
"fileName": "helper",
"fileComment": "Helper functions for mathematics calculations.",
"items": [
{
"isFunction": true,
"name": "sum",
"typeString": "(a: number, ...numbers: number[]) => number",
"comments": ["Sum up a set of numbers"],
"params": [
{
"name": "a",
"type": "number"
},
{
"name": "numbers",
"description": "numbers which you want to sum up",
"type": "number[]"
}
],
"returns": {
"type": "number",
"description": "sum of the numbers"
},
"jsDocTags": [
{
"name": "param",
"text": "numbers numbers which you want to sum up"
},
{
"name": "returns",
"text": "sum of the numbers"
}
]
},
{
"isFunction": false,
"name": "MAGIC_NUMBER",
"typeString": "number",
"comments": ["Some magic number"],
"jsDocTags": []
}
]
}
]
Options
tsDoc
accepts an options object as parameter. The options are:
- files (
string[]
, required): relative paths to files which you want to extract the typescript definitions. Note that you only need to provide the entries files; imported modules will automatically included. - excludes (
string[]
, optional): pattern to exclude specific files. Example:**/*.tsx
- showPrivate (
boolean
, optional): make members tagged with@private
to be exported. Default tofalse
. - warnIfParamMissingJsDoc (
boolean
, optional): warn if function parameter could not find is associated jsdoc comment. Default totrue
.
Supported Features
Currently this library only supports function and constants. Many Typescript constructs (e.g. type
and interface
) are not supported intentionally because your JavaScript library documentation should not requires Typescript knowledge. class
definition is currently not supported as I do not have use case of that; I seldom code in OOP.
- [x] function
- [x] constants
- [ ] class
File Overview
Warning: This is not a standard Typescript feature because there is no official way to provide file overview in current Typescript version as far as I know, so I invented my own convention. If you know the official supported syntaax to provide file overview in Typescript, raise an issue.
You can provide a short file overview for by adding // @overview: <your description>
magic comment at first line of the code.
Comparisons with other libraries
typedoc is handy if you want a standardized format of Typescript documentation, but it doesn't allows you to easily extract the metadata and use your own rendering logic. I personally find the documentation structure confusing.
api-extractor seems like allow you to do what this library does too, but it has higher learning curve.