Package Exports
- ts-code-api
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (ts-code-api) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
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.
- function
- 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.