Resolve documentation for type aliases

🔍 Search Terms

type alias hover documentation

✅ Viability Checklist

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

When a type is a literal type alias of another type without any generics, it should take over the documentation of the aliased type.

I originally proposed this in https://github.com/microsoft/TypeScript/issues/49798#issuecomment-1228787745, but I think this deserves its own issue.

📃 Motivating Example

Type aliases should resolve the documentation of the type they alias.

/**
 * A boolean, number, or string literal
 */
type PrimitiveLiteral = boolean | number | string

type Primitive = PrimitiveLiteral

// hovering on 'Primitive' should show "A boolean, number, or string literal"
let value: Primitive

💻 Use Cases

1. What do you want to use this for?

Type aliases are a common way to import types when using types in JSDoc. For example:

/**
 * @typedef {import('unist').Point}  Point
 */

/**
 * @param {Point} point
 */
function stringifyPoint(point) {}

2. What shortcomings exist with current approaches?

Hovering Point in the example, provides no documentation. When type definitions are generated, they create a type alias which has the same problem.

3. What workarounds are you using in the meantime?

Navigate to the original type to read its documentation, or look it up online.

Begin by tracing hover documentation for the Primitive alias and the JSDoc/import typedef example in the TypeScript language service. Compare current behavior with the requested inherited documentation for non-generic literal aliases, then add focused coverage and verify the hover output; the issue names no files or tests, so locating the relevant paths is part of the work.