About

structured-types is a collection of libraries using the Typescript Compiler API to generate "structured" type information from jsdoc and typescript files.

The library API extracts full types for your libraries, not just string representations of the type, and is built around a plugin architecture, so it can be extended to extract custom types for frameworks such as react, vue, angular.

Live example

You can use our Playground site to experiment with custom code

Using the API

More information about the @structured-types/api package.

1. Installation

$ npm install @structured-types/api --save-dev

2. Your API source file (sum.js):

/**
 * sum api function
 * @remarks
 * Unlike the summary, the remarks block may contain lengthy documentation content.
 * The remarks should not restate information from the summary, since the summary section
 * will always be displayed wherever the remarks section appears.  Other sections
 * (e.g. an `@example` block) will be shown after the remarks section.
 *
 * @param {number} a first parameter to add
 * @param {number} b second parameter to add
 * @returns {number} the sum of the two parameters
 *
 * @example
 *
 * ```js
 * import { sum } from './sum';
 *
 * expect(sum(1, 2)).toMatchObject({ a: 1, b: 2, result: 3});
 * ```
 */
export const sum = (a, b = 1) => ({ a, b, result: a + b });

3. Your documentation extraction

import { parseFiles } from '@structured-types/api';

const docs = parseFiles(['../src/sum.js']);

4. The result

{
  "sum": {
    "name": "sum",
    "kind": 11,
    "parameters": [
      {
        "kind": 2,
        "name": "a",
        "description": "first parameter to add"
      },
      {
        "kind": 2,
        "name": "b",
        "value": 1,
        "description": "second parameter to add"
      }
    ],
    "examples": [
      {
        "content": "```js\nimport { sum } from './sum';\n\nexpect(sum(1, 2)).toMatchObject({ a: 1, b: 2, result: 3});\n```"
      }
    ],
    "returns": {
      "description": "the sum of the two parameters",
      "kind": 2
    },
    "tags": [
      {
        "tag": "remarks",
        "content": "Unlike the summary, the remarks block may contain lengthy documentation content.\nThe remarks should not restate information from the summary, since the summary section\nwill always be displayed wherever the remarks section appears.  Other sections\n(e.g. an `@example` block) will be shown after the remarks section."
      }
    ],
    "description": "sum api function"
  }
}

Using the CLI

You can also use structured-types to automatically generate markdown README.md-type files for your libraries.

More information about the @structured-types/api-readme package.

1. Installation

$ npm install @structured-types/api-readme --save-dev

2. Configure

In your README.md (or other markdown file) file, you will insert a <api-readme /> tag to generate the API section:

<api-readme />

3. Launch

You can launch directly from the command-line ie yarn run api-readme or from your package.json file by adding a script to launch the command line documentation tool.

...
  "scripts": {
    "docs": "api-readme",
    ...
  },
...

Typescript playground plugin

Click to install our TypeScript playground plugin which shows the type information for the current file.

More information about the @structured-types/playground-plugin package.

chadhietala/structured-types

Table of contents

About

Live example

Using the API

1. Installation

2. Your API source file (sum.js):

3. Your documentation extraction

4. The result

Using the CLI

1. Installation

2. Configure

3. Launch

Typescript playground plugin

Roadmap