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

An issue has been encountered at the header component of an Angular web application, identified as error code

What is the best way to limit the types of function parameters in TypeScript based on whether the parameter index is even or odd?

Typescript - Troubleshooting undefined error with static variables

Transforming JavaScript to TypeScript in Angular: encountering error TS2683 stating that 'this' is implicitly of type 'any' due to lacking type annotation

Is the return type determined by the parameter type?

Dependency injection in Angular 2 service not functioning as expected

When converting a PDF to a PNG, the precious data often disappears in the process

When clicking initially, the default input value in an Angular 2 form does not get set

Example of Signature in TypeScript Function Declaration

After compilation, what happens to the AngularJS typescript files?

When attempting to display an identical image on two distinct canvas elements in Angular 6

Automatically activate the Focus Filterfield in the ng-multiselect-dropdown upon clicking

What could be the reason for the react hook form failing to capture the data upon submission?

How to bring in a class that was exported using `export = uuid` in Typescript

Unable to append item to document object model

Are there more efficient alternatives to utilizing arrays and index-based functions for storing in-memory data in TypeScript?

Experiencing a "HEROES not found" error while following an Angular guide

Tips for associating an id with PrimeNg menu command

What is the best method for conducting comprehensive testing of all projects and libraries within NestJS (nx)?

I am experiencing issues with the customsort function when trying to sort a column of