Work in progress 👷‍

tydoc

• API
  • renderMarkdown
  • fromProject
  • fromModule
  • Exported Types
    • I RenderMarkdownOptions
  • Type Index
    • I Options
    • T DocPackage
    • & DocModule
    • T TSDocFrag
    • I TSDoc
    • & DocTypeUnion
    • | Node
    • T DocTypePrimitive
    • T DocTypeLiteral
    • & DocTypeAlias
    • T RawFrag
    • & DocTypeInterface
    • T DocProp
    • & DocTypeCallable
    • T DocSig
    • T DocSigParam
    • T DocTypeArray
    • & DocTypeObject
    • T DocTypeIndexRef
    • & DocUnsupported
    • & DocTypeIntersection
    • T Expor
    • I Options
    • I Settings
    • F Thunk
• Internal Development

API

(docs: DocPackage, opts: Options) => string

fromProject

(opts: Options) => DocPackage

fromModule

(manager: Manager, sourceFile: SourceFile) => DocPackage

Exported Types

I RenderMarkdownOptions

typeIndexRef

Type Index

I Options

export interface Options {
  /**
   * Whether or not the API terms section should have a title and nest its term
   * entries under it. If false, term entry titles are de-nested by one level.
   */
  flatTermsSection: boolean
}

T DocPackage

//
// Package node
//

export type DocPackage = {
  modules: DocModule[]
  typeIndex: TypeIndex
}

& DocModule

//
// Module Node
//

export type DocModule = TSDocFrag & {
  kind: 'module'
  name: string
  /**
   * The path to this module from package root. If this module is the root
   * module then the path will be `/`.
   *
   * @remarks
   *
   * This is what a user would place in their import `from `string _following_ the
   * package name. For example:
   *
   * ```ts
   * import foo from "@foo/bar/quux/toto"
   * //                       ^^^^^^^^^^
   * ```
   */
  path: string
  isMain: boolean
  mainExport: null | Node
  namedExports: Expor[]
  location: {
    absoluteFilePath: string
  }
}

T TSDocFrag

//
// Node Features
//

export type TSDocFrag = {
  tsdoc: null | TSDoc
}

I TSDoc

export interface TSDoc {
  raw: string
  summary: string
  examples: { text: string }[]
  customTags: { name: string; text: string }[]
}

& DocTypeUnion

//
// Union Node
//

export type DocTypeUnion = {
  kind: 'union'
  isDiscriminated: boolean
  discriminantProperties: null | string[]
  types: Node[]
} & RawFrag

| Node

export type Node =
  | DocTypeUnion
  | DocTypePrimitive
  | DocTypeLiteral
  | DocTypeAlias
  | DocTypeInterface
  | DocTypeCallable
  | DocTypeArray
  | DocTypeObject
  | DocTypeIndexRef
  | DocUnsupported
  | DocTypeIntersection
  // todo unused?
  | { kind: 'function'; signatures: DocSig[] }
  | ({
      kind: 'callable_object'
      signatures: DocSig[]
      properties: DocProp[]
    } & RawFrag)
  | ({
      kind: 'callable_interface'
      properties: DocProp[]
      signatures: DocSig[]
    } & RawFrag)

T DocTypePrimitive

export type DocTypePrimitive = { kind: 'primitive'; type: string }

T DocTypeLiteral

export type DocTypeLiteral = { kind: 'literal'; base: string }

& DocTypeAlias

export type DocTypeAlias = {
  kind: 'alias'
  name: string
  type: Node
} & RawFrag &
  TSDocFrag

T RawFrag

export type RawFrag = {
  raw: {
    typeText: string
    nodeText: string
    nodeFullText: string
  }
}

& DocTypeInterface

export type DocTypeInterface = {
  kind: 'interface'
  name: string
  props: DocProp[]
} & RawFrag &
  TSDocFrag

T DocProp

export type DocProp = { kind: 'prop'; name: string; type: Node }

& DocTypeCallable

export type DocTypeCallable = {
  kind: 'callable'
  isOverloaded: boolean
  hasProps: boolean
  sigs: DocSig[]
  props: DocProp[]
} & RawFrag

T DocSig

export type DocSig = { kind: 'sig'; params: DocSigParam[]; return: Node }

T DocSigParam

export type DocSigParam = { kind: 'sigParam'; name: string; type: Node }

T DocTypeArray

export type DocTypeArray = { kind: 'array'; innerType: Node }

& DocTypeObject

export type DocTypeObject = { kind: 'object'; props: DocProp[] } & RawFrag

T DocTypeIndexRef

/**
 * A link to the type index. All named types go into the type index. When a type
 * or export includes a named type, rather than documenting it inline, a
 * reference to the type index is created.
 *
 */
export type DocTypeIndexRef = {
  kind: 'typeIndexRef'
  /**
   * An identifier that can be used to lookup the type in the type index.
   *
   * @example
   *
   * ```ts
   * docs.typeIndex[typeIndexRef.link]
   * ```
   */
  link: string
}

& DocUnsupported

export type DocUnsupported = { kind: 'unsupported' } & RawFrag

& DocTypeIntersection

//
// Intersection Node
//

export type DocTypeIntersection = {
  kind: 'intersection'
  types: Node[]
} & RawFrag

T Expor

//
// Export Node
//

export type Expor = {
  kind: 'export'
  name: string
  isTerm: boolean
  isType: boolean
  type: Node
}

I Options

interface Options {
  /**
   * Paths to modules in project, relative to project root or absolute.
   */
  entrypoints: string[]
  project?: tsm.Project
  /**
   * Specify the path to the package's entrypoint file.
   *
   * @defualt Read from package.json main field
   * @remarks This is useful for tests to avoid mocks or environment setup
   */
  packageMainEntrypoint?: string
  /**
   * Specify the root of the project.
   *
   * @default The current working directory
   * @remarks This is useful for tests to avoid having to mock process.cwd
   */
  prjDir?: string
  readSettingsFromJSON: boolean
  /**
   * Sometimes a source entrypoint is fronted by a facade module that allows
   * package consumers to do e.g. `import foo from "bar/toto"` _instead of_
   * `import foo from "bar/dist/toto". Use this mapping to force tydoc to view
   * the given source modules (keys) at the given package path (values).
   *
   * @example
   *
   * Given project layout:
   *
   * ```
   * /src/foo/bar/toto.ts
   * ```
   *
   * The setting:
   *
   * ```ts
   * sourceModuleToPackagePathMappings: {
   *    "foo/bar/toto": "toto"
   * }
   * ```
   *
   * Will cause the `toto` module to be documented as being available at path:
   *
   * ```ts
   * import some from "thing/toto"
   * ```
   */
  sourceModuleToPackagePathMappings?: Record<string, string>
}

I Settings

export interface Settings {
  /**
   * Absolute path to the source root. This should match the path that rootDir
   * resolves to from the project's tsconfig.json.
   */
  srcDir: string
  prjDir: string
  mainModuleFilePathAbs: string
  sourceModuleToPackagePathMappings?: Record<string, string>
}

F Thunk

export type Thunk<T> = () => T