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;
}

...and TypeDoc places it under the "Interfaces" section/"folder".

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". Also, by using ReadOnly the type is very verbose, but I suppose that's just how it works.

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.

[tgreyuk]

This is not something this plugin can control and in any case it is not currently achievable. There are noises that it may be possible in the future. These references should provide further background:

• Support documentation for string literal types in unions TypeStrong/typedoc#1148
• RFC: Specify that doc comments are allowed on simple union types microsoft/tsdoc#164

[mrousavy]

Oh I see, thanks 👍

[tgreyuk]

Closing as duplicate of TypeStrong/typedoc#1540.