please alias jsdoc doc comments to variable assignments

[trusktr]

Suggestion

🔍 Search Terms

typescript alias jsdoc to variable assignment

✅ Viability Checklist

My suggestion meets these guidelines:

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

⭐ Suggestion

Please copy JSDoc data to aliased variables.

📃 Motivating Example

/** Call this in order to something. */
const foo = (s: string): number => 123

const f = foo

f // hovering on 'f' does not show the documentation description "Call this in order to something."

playground

💻 Use Cases

Make documentation easier. All projects need good documentation!

Workaround:

an author can copy/paste duplicate JSDoc comments. This is harder to maintain.

[fregante]

Just in time! I was looking for exactly this now. I tried several JSDoc options but nothing seems to be able to copy the description the right way (@typedef, @inheritDocs, @borrows, @augments, …)

[trusktr]

Is more feedback needed from me? Or from a team member? Not sure what the tag implies.

[remcohaszing]

Could this also be applied to type aliases too?

/**
 * This is a type
 */
type Foo = string | number

type Bar = Foo

// hovering on 'Bar' does not show the documentation description "This is atype"
export { Bar }

This is especially useful for types in jsdoc

/**
 * @typedef {import('vscode-languageserver-types').Range} Range
 */

// jsdoc information is lost for 'Range'
/**
 * @param {Range} range
 */
function handleRange(range) {}

[unional]

/**
 * what this type is about
 */
export type Foo = () => void

const foo: Foo // `foo` should get `Foo` jsdoc if itself does not have one.

[verikono]

Big props to this... If i get another sermon about semantic reasoning from my boss I think I shall surely die... He's all about those multilevel type aliasing, type branding and guarding and now he's worked out that with async/await everywhere... those type guards are getting very very very composed... unlike myself.

[trusktr]

Here's a video showing the issue:

https://user-images.githubusercontent.com/297678/224135023-6bc4b96a-042b-4f43-845d-f9fac7aa1e64.mov