How to document types? (Unions and Intersection Types)

[mrousavy]

Search Terms

type, export type, types, interface, interfaces, union type, intersection type, unions

Problem

Can't document union types

It is not possible to document the individual values of union types, so I have to adjust the description to manually list them:

/**
 * Represents the camera device position.
 *
 * * `"back"`: Indicates that the device is physically located on the back of the system hardware
 * * `"front"`: Indicates that the device is physically located on the front of the system hardware
 *
 * #### iOS only
 * * `"unspecified"`: Indicates that the device's position relative to the system hardware is unspecified
 *
 * #### Android only
 * * `"external"`: The camera device is an external camera, and has no fixed facing relative to the device's screen. (Android only)
 */
export type CameraPosition = 'front' | 'back' | 'unspecified' | 'external';

Is there a better solution for this so I can correctly document each union (front, back, ...) with TypeDoc checking if I missed anything and even allowing me to link to it?

No "types" category in output

Documenting an interface is easy;

/**
 * document Point here
 */
export interface Point {
  /**
   * document x here
   */ 
  x: number;
  /**
   * document x here
   */ 
  y: number;
}

But if I make Point a type instead of an interface;

/**
 * document Point here
 */
export type Point = ReadOnly<{
  /**
   * document x here
   */ 
  x: number;
  /**
   * document x here
   */ 
  y: number;
}>;

...TypeDoc does not place Point under a "types" section in the output but rather "ignores" it so you can only find it under "Modules".

You can see this in action at VisionCamera documentation, where there is an "Interfaces" section on the left but no "Types" (or "Unions" or whatever) section. Instead, CameraPosition can only be found under "Modules" > "CameraPosition".

Suggested Solution

Add a "Types" output category just like "Interfaces", and allow individual union types to be documented.

[Gerrit0]

Can't document union types

This is the "union enums" request - microsoft/tsdoc#164. I plan to get around to this eventually, but haven't gotten to it yet... there's another change I want to make to how type aliases are resolved in 0.21, so this will probably happen then.

No "types" category in output

This looks like a problem with your theme to me. The default theme includes a "Type Aliases" section. https://typedoc.org/api/modules.html

[Gerrit0]

Going to track the union-enums under #1710, since it's more easily searchable. The other issue seems to be a problem with your theme, not TypeDoc.