getdocs-ts

getdocs-ts

This is a tool for extracting documentation and typing information from TypeScript sources. The output is intended for further processing with builddocs.

Usage

$ bin/getdocs-ts.js some-source.ts > some-symbols.json

Or via the API:

const {gather} = require("getdocs-ts")

let items = gather({filename: "/path/to/mainfile.ts"})

You can also pass a basedir option to gather, which provides the directory inside which imported files should be considered internal to the module. This defaults to the parent directory of the main filename.

A second function gatherMany, takes an array of configurations and extracts them all at once. Because this avoids duplicate startup, typechecking, and module loading work, this can be a lot faster when generating docs for a bunch of modules at once.

The tool will omit declarations with a doc comment that includes @internal or @hide from its output.

Output format

These declarations summarize the structore of the returned values. gather returns a {[name: string]: Item} object, listing all the top-level exported items.

export type BindingKind = "class" | "enum" | "enummember" | "interface" |
  "variable" | "property" | "method" | "typealias" | "typeparam" |
  "constructor" | "function" | "parameter" | "reexport"

export type Loc = {file: string, line: number, column: number}

export type Binding = {
  kind: BindingKind,
  id: string,
  description?: string,
  loc?: Loc,
  abstract?: boolean,
  readonly?: boolean,
  optional?: boolean
}

export type BindingType = {
  type: string,
  typeSource?: string, // missing means this is a built-in type
  typeParamSource?: string,
  properties?: {[name: string]: Item},
  instanceProperties?: {[name: string]: Item},
  typeArgs?: readonly BindingType[],
  typeParams?: readonly Param[],
  // Used by mapped types
  key?: Param,
  signatures?: readonly CallSignature[],
  extends?: BindingType,
  construct?: Item,
  implements?: readonly BindingType[]
}

export type CallSignature = {
  type: "function" | "constructor",
  params: readonly Param[],
  returns?: BindingType,
  typeParams?: readonly Param[]
}

export type Param = BindingType & {
  name?: string,
  id: string,
  kind: "parameter" | "typeparam",
  description?: string,
  loc?: Loc,
  optional?: boolean,
  rest?: boolean,
  default?: string
}

export type Item = Binding & BindingType

License

This program is free software: you can redistribute it and/or modify it under the terms of the MIT license. See LICENSE for a copy of the license.