Edit

About API docs

These docs are auto-generated by generate-api-docs.js which generates the docs based on the ambient typings files within the repository (the *.d.ts files). See below for more info.

If you are using an editor that uses the typescript language service (e.g. vs-code, visual studio, webstorm/intelliJ), you should be able to hover over the definitions within your editor to get the same documentation.

Please open any issues if you find any within these docs. Open pull requests modifying the *.d.ts files.

How these docs work

These docs work by parsing the ambient typings files (*.d.ts) files in /src and turning them into markdown files (*.md).

This works by using the typescript API (i.e. const ts = require('typescript');) to parse the ambient typings for JS doc comments, interfaces, and other code.

The generator will only pick up code that is commented with a JSDoc comment that contains the @docs directive.

//    this comment must be a JSDoc comment
// 👇 (which is more than a multi-line comment)
/**
 * @docs Title of `module`
 *
 * Description of module. You can also put _markdown_ in **here**
 */
function myModule(x: number): string;

This will generate the following document:

---

Title of module

Description of module. You can also put markdown in here

function module(x: number): string;

---

Generating tables for interfaces

When you put the @docs directive above an interface, the generator will go through all the property declarations and generate a table.

/**
 * @docs `ExampleModule`
 *
 * This is a description of `ExampleModule`
 */
interface ExampleModule {
  /**
   * This is the description of foo.
   */
  foo: string;
  /**
   * This is the description of bar.
   */
  bar?: number;
}

---

ExampleModule

This is a description of ExampleModule

Name	Description	Type	Required
foo	This is the description of foo.	string	yes
bar	This is the description of bar.	number	no

---

Other code behavior

When the generator sees the @docs directive in a JSDoc comment before anything else that isn't an interface, it will simply take the declaration and wrap it in a code block with one difference—it will remove the generics from the types (e.g. <T>).

Why? Non-TS users are confused by generics. Simply removing the generics declaration (i.e. the stuff between the <>s) fixes the readability issue while also keeping the generics there.

For example, see the input code block vs the output code block.

Input:

export function myModule<Foo, Bar, Args extends any[], Result>(
  ...args: Args
): {
  foo: Foo;
  bar: (bar: Bar) => Result;
};

Output (more readable to JS users):

function myModule(
  ...args: Args
): {
  foo: Foo;
  bar: (bar: Bar) => Result;
};