Creating comprehensive and elaborate intellisense documentation for Typescript Union Types

Question

Creating comprehensive and elaborate intellisense documentation for Typescript Union Types

When we call the baz function with the code provided, the typeahead will display 'a' and 'b' as potential values.

https://i.stack.imgur.com/SrKo7.png

If additional documentation is needed for each of these values, how can it be accomplished? For example, if the desired outcome is:

https://i.stack.imgur.com/Bbipq.png

To provide more context on the intention and purpose, let's consider the following example:

const paintColor = {
  /** This color is good fo X */
  Waltz: "#d9e5d7",
  /** This color is good fo Y */
  "Indiana Clay": "#ed7c4b",
  /** This color is good fo Z */
  Odyssey: "#575b6a"
};

const locations = {
  /** There are no good school at this location*/
  City: "123 city center road",
  /** There are lots of parking at this location but it is very far*/
  West: "245 some other road"
};

interface HouseProp {
  color: keyof typeof paintColor; //"Waltz" | "Indiana Clay" | "Odyssey"
  location: keyof typeof locations; //"City" | "West"
}

const House = ({ color, location }: HouseProp) => {
  ...
};

A react component called House renders a house based on the color and location props.

This House component is utilized extensively across the project.

Despite the current configuration, using House like this does not reflect the documented details in IntelliSense:

https://i.stack.imgur.com/ugG2L.png

The desired outcome would resemble this:

https://i.stack.imgur.com/4o4tt.png

Regarding the issue, while enums could be created for `paintColor` and `locations`, implementing them may not align with the original proposal.

import House, {HouseColor, HouseLocation} from './House';
<House color={HouseColor["Indiana Clay"]} location={HouseLocation.City} />

However, this approach lacks the elegance of the initial suggestion for the component interface.

typescript documentation intellisense jsdoc tsdoc

Answer 1

Answer №1

When dealing with union members, annotating them can be a challenge. However, you can approach this issue in a different way by utilizing function overloads or opting for an enum instead.

Solution #1: Leveraging Function Overloads

/**
 * a is suitable for X
 */
function baz(param: 'a'): number;
/**
 * b is a great choice for Y
 */
function baz(param: 'b'): number;
function baz(param: 'a' | 'b'): number {
  return 1;
}

Screenshot

Solution #2: Using Overload as an Interface

interface Baz {
  /**
   * a is appropriate for X
   */
  (param: 'a'): number;
  /**
   * b is a fantastic choice for Y
   */
  (param: 'b'): number;
}

const baz: Baz = (param: 'a' | 'b') => {
  return 1;
}

Screenshot

Solution #3: Opting for an Enum Instead

enum Foo {
  /**
   * a is suitable for X
   */
  A = 'a',
  /**
   * b is a great choice for Y
   */
  B = 'b',
}

function baz(param: Foo) {
  return 1;
}

Screenshot

While this may not be the exact solution you were hoping for, it presents a viable alternative.

Answer 2

When dealing with union members, annotating them can be a challenge. However, you can approach this issue in a different way by utilizing function overloads or opting for an enum instead.

Solution #1: Leveraging Function Overloads

/**
 * a is suitable for X
 */
function baz(param: 'a'): number;
/**
 * b is a great choice for Y
 */
function baz(param: 'b'): number;
function baz(param: 'a' | 'b'): number {
  return 1;
}

Screenshot

Solution #2: Using Overload as an Interface

interface Baz {
  /**
   * a is appropriate for X
   */
  (param: 'a'): number;
  /**
   * b is a fantastic choice for Y
   */
  (param: 'b'): number;
}

const baz: Baz = (param: 'a' | 'b') => {
  return 1;
}

Screenshot

Solution #3: Opting for an Enum Instead

enum Foo {
  /**
   * a is suitable for X
   */
  A = 'a',
  /**
   * b is a great choice for Y
   */
  B = 'b',
}

function baz(param: Foo) {
  return 1;
}

Screenshot

While this may not be the exact solution you were hoping for, it presents a viable alternative.

Answer 3

Answer №2

A current limitation in TypeScript involves handling string literals within union types, but it is unclear if this issue is being addressed. An example can be found in the TypeScript repository under issue ticket Support parsing TSDoc string comments #38106. Show your support for this ticket by giving it a thumbs up and subscribing to receive updates on its progress (while refraining from simple comments like "+1" or "me too").

Additionally, there are related issues in the TSDoc and typedoc repositories discussing similar topics: RFC: Specify that doc comments are allowed on simple union types #164 and Support for enum-like use of string literal types #1710.

If you require hover information for enumeration values, consider utilizing TypeScript's enum feature as a workaround, even though it may not be the desired solution. For instance:

/** FOO */
enum Foo {
   /** AAA */
   a = "a",
   /** BBB */
   b = "b",
   /** CCC */
   c = "c",
};
type FooArray = Foo[];

const foo = Foo.a;
const fooArray: FooArray = [Foo.a, Foo.b, Foo.c];

By hovering over the "a" in "Foo.a", you should see a tooltip displaying "AAA" for reference.

Answer 4

A current limitation in TypeScript involves handling string literals within union types, but it is unclear if this issue is being addressed. An example can be found in the TypeScript repository under issue ticket Support parsing TSDoc string comments #38106. Show your support for this ticket by giving it a thumbs up and subscribing to receive updates on its progress (while refraining from simple comments like "+1" or "me too").

Additionally, there are related issues in the TSDoc and typedoc repositories discussing similar topics: RFC: Specify that doc comments are allowed on simple union types #164 and Support for enum-like use of string literal types #1710.

If you require hover information for enumeration values, consider utilizing TypeScript's enum feature as a workaround, even though it may not be the desired solution. For instance:

/** FOO */
enum Foo {
   /** AAA */
   a = "a",
   /** BBB */
   b = "b",
   /** CCC */
   c = "c",
};
type FooArray = Foo[];

const foo = Foo.a;
const fooArray: FooArray = [Foo.a, Foo.b, Foo.c];

By hovering over the "a" in "Foo.a", you should see a tooltip displaying "AAA" for reference.

Creating comprehensive and elaborate intellisense documentation for Typescript Union Types

Answer №1

Answer №2

Similar questions

Uncover the content of a base64 encoded string and convert it into

Warning: The attribute 'EyeDropper' is not recognized within the context of 'Window & typeof globalThis'

Is there a way to toggle the visibility of the angular material toolbar at regular intervals?

Applying TPS rate to existing API endpoints at the method level within API Gateway using AWS CDK

"Facing an issue where ts-node is not recognizing d.ts files, despite tsc being able to compile them

Angular fails to retrieve the data from an Object

Having trouble implementing object type switching in Typescript

Explain the TypeScript type where the keys of an object not found in an array should correspond to the type of another object

arrange elements by their relationship with parents and children using typescript and angular

Function exported as default in Typescript

When employing GraphQL Apollo refetch with React, the update will extend to various other components as well

What is the best way to dynamically disable choices in mat-select depending on the option chosen?

The type 'TaskListProps[]' cannot be assigned to type 'TaskListProps'

Error in Typescript TS2322: Observable Type 'boolean | {}' - Using Angular 5 and Typescript 2.4.2

Integrating Constant Contact API into a Next.js application

The type '{}' does not contain a property named 'map'

Efficient ways to manage dropdown cells in ReactGrid

Angular array of considerable size

How can Observables be designed to exhibit both synchronous and asynchronous behavior?

The type 'Promise<any>' cannot be assigned to the type 'Contact[]'