Typescoop
Typescoop generates API documentation from your TypeScript types and JSDoc comments. It reads your source with the TypeScript compiler and writes a JSON model that the TypeDocProps component renders as a props table.
Typescoop is a replacement for our legacy
@qualcomm-ui/typedocpackage. It uses the TS compiler API directly to generate types significantly faster and more accurately.
Overview
Consider the following example:
export type WeightUnit = "kg" | "lb"
export interface Dog {
/**
* The age of the dog in human years.
*/
age: number
/**
* The breed of the dog.
*/
breed?: string
/**
* The name of the dog.
*/
name: string
/**
* The weight of the dog. Refer to {@link weightUnit} for unit type
* information.
*/
weight?: number
/**
* The unit type of the {@link weight} field.
*
* @option `'kg'`: kilograms.
* @option `'lb'`: pounds.
*/
weightUnit?: WeightUnit
}Typescoop collects the exported Dog interface, resolves each property's type, and writes the result to a JSON file. Reference the interface by name in the TypeDocProps component to render its documentation:
<TypeDocProps name="Dog" />numberstringstringnumber'kg' | 'lb'
Features
- JSDoc comment and tag parsing.
- Links between properties of the same interface.
- Union expansion and reference type resolution.
- Inline printing of small object types.
- Import statements for referenced types.
- Property anchor links, including same-page collision resolution.
- Formatted type output.
- Required and deprecated property indicators.
- Angular input, output, and public method grouping.
- Watch mode with incremental rebuilds.
Getting Started
Install Packages
npm i --save-dev @qualcomm-ui/typescoop @qualcomm-ui/tsconfig
Initialize the config
Run the command and follow the prompts to generate the config:
typescoop initThe command asks for a file type, an output file, and a tsconfig path, then writes the config file. Typescoop looks for its config with cosmiconfig, so typescoop.config.ts, typescoop.config.js, and typescoop.config.json all work.
// typescoop.config.ts
import type {BuildOptions} from "@qualcomm-ui/typescoop"
export default {
logMode: "info",
outputFile: ".typescoop/type-data.json",
tsconfig: "tsconfig.typescoop.json",
} satisfies BuildOptionsRun command
typescoop extract generates the JSON once. Add -w to watch source files for changes and rebuild. Use --config <path> to point at a config file in a different location.
Connect the docs site
Set the typeDocProps option in your QUI Docs config to the output file:
// qui-docs.config.ts
import type {QuiDocsConfig} from "@qualcomm-ui/mdx-vite"
export default {
// ...
typeDocProps: ".typescoop/type-data.json",
} satisfies QuiDocsConfigThe output is generated, so add the output directory to your .gitignore.
Entry Points
Typescoop documents the exports of each entry point. By default, the entry points are the files included by your tsconfig. You can set entryPoints in the config instead. Directories are expanded recursively to every .ts, .tsx, and .d.ts file they contain.
// typescoop.config.ts
import type {BuildOptions} from "@qualcomm-ui/typescoop"
export default {
// optional. If omitted, the entry points are the files included
// by the tsconfig.
entryPoints: ["./src/index.ts"],
tsconfig: "tsconfig.typescoop.json",
} satisfies BuildOptionstsconfig
The tsconfig defines the compiler options and, unless entryPoints is set, the files to document. Extend the default configuration from @qualcomm-ui/tsconfig to simplify setup. Type checking is not required to extract types, so compileOptions.noCheck is set by default.
// tsconfig.typescoop.json
{
"extends": "@qualcomm-ui/tsconfig/tsconfig.typedoc.json",
"include": ["./src"],
"exclude": ["**/*.spec.ts", "**/*.spec.tsx"],
}Typescoop reads TypeScript source directly, so you don't need to build your packages first. Pointing at src also keeps type information that is lost in compiled declarations, such as Angular decorators.
Multiple Packages
If your library depends on another package in your workspace, include that package's source in the tsconfig as well.
Consider an example project with the following structure:
reactdepends onbase.react-docscontains the Typescoop config.
The tsconfig needs to include both packages:
{
"extends": "@qualcomm-ui/tsconfig/tsconfig.typedoc.json",
"include": ["../base/src", "../react/src"],
}If a package's imports resolve to its compiled output, add paths so that they resolve to source instead:
{
"extends": "@qualcomm-ui/tsconfig/tsconfig.typedoc.json",
"compilerOptions": {
"paths": {
"@my-org/base/*": ["../base/src/*"],
},
},
"include": ["../base/src", "../react/src"],
}External Types
Declarations that live in node_modules are treated as external. They are never documented as entities, and inherited members declared there, such as DOM attributes on an interface that extends HTMLAttributes, are left out of the props table. Properties that reference external types still print the type name.
Type Detection
Typescoop decides which exports end up in the output with the documentationScope option.
all(default): every exported entity is documented. This increases the size of the JSON output.only-public: an entity is documented when its JSDoc comment has the@publictag, or when it comes from a package listed inmoduleWhitelist.
export interface ButtonProps {
// ...
}The following rules apply regardless of scope:
- Only exports of the entry points are collected. Re-exports and aliases are followed to their declarations.
- Functions, and variables that hold untyped arrow functions or function expressions, need a JSDoc comment to be documented. A comment with only the
@publictag counts. - Default exports are named after their file.
- If two entry points export the same name, the one listed last in
entryPointsis used. Files in a directory entry point are processed in path order. - Entities and members tagged with
@internalare excluded. - Members with the
privateorprotectedmodifier, and#privatemembers, are excluded. Methods and accessors need a JSDoc comment. Properties are included without one.
If TypeDocProps reports that an entity was not found, check that the entity is exported from an entry point and, with the only-public scope, that it has the @public tag.
Inherited Comments
A class without a JSDoc comment uses the comment of its nearest documented base class. A class member without a comment uses the comment of the member it overrides or implements. This lets a component class pick up the property documentation from the interface it implements.
Reference Types
Unexported types are not expanded. Consider this example:
interface InternalDefinition {
/**
* Some function
*/
someFn: (args: string) => void
}
export interface ExternalDefinition {
/**
* Property
*/
property: InternalDefinition
}InternalDefinition is not exported, so the documentation for ExternalDefinition.property only shows the type name. Export InternalDefinition to show its structure.
JSDoc Tags
The following tags have special handling in Typescoop or the UI.
@default
Use the @default tag to indicate a default value for a property. Values that aren't already in a code block are rendered as TypeScript.
export interface DefaultTagExample {
/**
* Example property.
*
* @default 0
*/
age?: number
}number@deprecated
Marks a property as deprecated. The UI shows a deprecated indicator next to the property.
export interface DeprecatedTagExample {
/**
* The size of the element. Use {@link size} instead.
*
* @deprecated
*/
legacySize?: number
/**
* The size of the element.
*/
size?: number
}numbernumber@inheritDoc
Prints the type as written, without expanding it. This is useful for types that reference themselves or expand into something long.
export interface Option {
/**
* Unique identifier for the option.
*/
id: string
/**
* Nested options.
*
* @inheritDoc
*/
options?: Option[]
/**
* Option value.
*/
value: string
}@custom
Replaces the printed type with the text after the tag. Use it when the real type is too complex to be useful in the docs.
export interface CustomTagExample {
/**
* Called when the value changes.
*
* @custom (value: string) => void
*/
onValueChange?: <T extends string = string>(value: T) => void
}(
value: string,
) => void
@docLink
Links a type to a page on the docs site. Properties that reference the type link to that page.
/**
* Page data, defined in each MDX file's frontmatter section.
*
* @docLink /api/page-frontmatter
*/
export interface PageFrontmatter {
// ...
}To link types that you don't own, use the referenceLinks option instead.
@link
Context is applied conditionally to the inline @link tag. @linkcode and @linkplain are handled the same way.
- If the link starts with
https, it's treated as an external link. - If the tag refers to a named property, it's treated as an internal link.
export interface LinkExample {
/**
* Visit {@link https://google.com this external link} to learn more.
*/
externalLink?: string
/**
* Refer to the {@link externalLink} property.
*/
internalLink?: string
}stringstring@option
Renders a bullet list entry for each option. Useful for documenting union or enum types.
export type WeightUnit = "kg" | "lb"
export interface OptionTagExample {
/**
* The unit type of the weight field.
*
* @option `'kg'`: kilograms.
* @option `'lb'`: pounds.
*/
weightUnit: WeightUnit
}'kg' | 'lb'
@see
Use the @see tag to render a separate section of documentation in the JSDoc comment. This is typically used to highlight related types or interfaces.
export interface SeeTagExample {
/**
* @see {@link someOtherPropExample}
*/
otherPropExample?: string
/**
* Another prop.
*/
someOtherPropExample?: string
}stringstring@since
The @since tag is used to indicate when a property was added. The default configuration assumes that you have a changelog at /changelog, but this can be modified per instance of TypeDocProps using the changelogPathname prop:
<TypeDocProps changelogPathname="/changelogs/mdx-docs" name="SinceExample" />export interface SinceExample {
/**
* Foo.
*
* @since 3.10.0
*/
foo: string
}@internal
Excludes an entity or member from the output.
export interface HiddenTagExample {
/**
* Hidden from the docs.
*
* @internal
*/
internalState?: unknown
/**
* Shown in the docs.
*/
label?: string
}stringAngular
Classes decorated with @Component or @Directive are documented as Angular components. Their members are grouped into inputs, outputs, and public methods.
- Signal inputs (
input(),input.required(),model()) and@Input()decorators are inputs. - Signal outputs (
output()) and@Output()decorators are outputs. - Input and output aliases are used as the property name.
- Required inputs are marked as required.
- Signal types print their value type, so
input<string>()prints asstring.
Use the angularConfig prop on TypeDocProps to choose which group to render:
<TypeDocProps name="ButtonDirective" />
<TypeDocProps angularConfig={{output: true}} name="ButtonDirective" />
<TypeDocProps angularConfig={{publicMethods: true}} name="ButtonDirective" />Configuration
Refer to the API reference for every option. The options below cover the most common customizations.
Import Resolver
When a property references a named type, the UI can show the import statement for that type. The importResolver option returns that statement. It receives details about the reference, such as the type name, the packageName it comes from, and the packagePath of its source file. Return undefined to skip the import.
// typescoop.config.ts
import type {BuildOptions} from "@qualcomm-ui/typescoop"
export default {
importResolver: ({name, packageName, packagePath}) => {
if (packageName === "@my-org/react") {
// src/button/button.tsx -> @my-org/react/button
const subModule = packagePath.split("/")[1]
return `import {${name}} from "${packageName}/${subModule}"`
}
if (packageName === "@types/react") {
return `import {${name}} from "react"`
}
},
tsconfig: "tsconfig.typescoop.json",
} satisfies BuildOptionsFor wrapper types, the resolver also receives typeArguments and a resolveImport function, which you can use to return the import of an inner type instead:
importResolver: async (params) => {
if (params.name === "WithDataAttributes" && params.typeArguments[0]) {
return params.resolveImport(params.typeArguments[0])
}
// ...
}Reference Links
Use referenceLinks to link type names to pages on your docs site. This works for any type, including types you don't own.
// typescoop.config.ts
import type {BuildOptions} from "@qualcomm-ui/typescoop"
export default {
referenceLinks: {
RenderProp: "/render-props#render-prop",
},
tsconfig: "tsconfig.typescoop.json",
} satisfies BuildOptionsModule Whitelist
With the only-public scope, every entity from a package listed in moduleWhitelist is documented, even without the @public tag.
// typescoop.config.ts
import type {BuildOptions} from "@qualcomm-ui/typescoop"
export default {
moduleWhitelist: ["@my-org/react", "@my-org/core"],
tsconfig: "tsconfig.typescoop.json",
} satisfies BuildOptionsInline Objects
Small documented object types are printed inline in place of their name, such as {end: DateValue; start: DateValue}. Use inlineObjects to change the limits. Objects with more than maxMembers members, or whose inline form is longer than maxLength characters, keep their name.
// typescoop.config.ts
import type {BuildOptions} from "@qualcomm-ui/typescoop"
export default {
inlineObjects: {
maxLength: 80,
maxMembers: 4,
},
tsconfig: "tsconfig.typescoop.json",
} satisfies BuildOptionsMigrating from Typedoc
Typescoop replaces @qualcomm-ui/typedoc. It no longer depends on TypeDoc, and its output works with the same TypeDocProps component from @qualcomm-ui/react-mdx.
- Replace the
@qualcomm-ui/typedocdev dependency with@qualcomm-ui/typescoop. - Rename
qui-typedoc.config.tstotypescoop.config.tsand update theBuildOptionsimport to@qualcomm-ui/typescoop. - Move
entryPointsandtsconfigout oftypedocOptionsto the top level of the config, then removetypedocOptions. Other TypeDoc options have no equivalent. - Replace
qui-typedocwithtypescoopin your package scripts. - Point your tsconfig and entry points at
srcinstead ofdist. Typescoop doesn't need compiled types. - The default output file changed from
.typedoc/doc-props.jsonto.typescoop/type-data.json. UpdatetypeDocPropsin your QUI Docs config and your.gitignore, or setoutputFileto keep the old path.
// before: qui-typedoc.config.ts
import type {BuildOptions} from "@qualcomm-ui/typedoc"
export default {
typedocOptions: {
entryPoints: ["./dist/index.d.ts"],
tsconfig: "tsconfig.typedoc.json",
},
} satisfies BuildOptions// after: typescoop.config.ts
import type {BuildOptions} from "@qualcomm-ui/typescoop"
export default {
entryPoints: ["./src/index.ts"],
tsconfig: "tsconfig.typescoop.json",
} satisfies BuildOptions