Support @var or @member JSDoc tags · Issue #56674 · microsoft/TypeScript (original) (raw)

🔍 Search Terms

jsdoc
@var
@member

✅ 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 isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

Recognize and support JSDoc's @var or @member tags.

📃 Motivating Example

It will allow the declaration of globals in JS files that use JSDoc for checking that are not declared within that specific file.

This will then allow for tools and tool chains that add to the global scope for a file or program to be documented without using ts, d.ts or other ts exclusive notation and features.

💻 Use Cases

1. What do you want to use this for?

Electron preload scripts and contextBridge.exposeInMainWorld!

1. What workarounds are you using in the meantime?

/**@type {import("./preload.js").ElectronAPI} */ var ElectronAPI;

1. What shortcomings exist with current approaches?

Relies on JS's support of variable redeclaration. Changing var to let throws the following error on runtime:

Identifier 'ElectronAPI' has already been declared

The following should do the same as the two lines above, but neither vscode nor TS supports it.

/** @var {import("./preload.js").ElectronAPI} ElectronAPI */

It does not rely on confusion inducing variable redeclaration and is much cleaner.

I believe it is also a way to declare members of a class without declaring them at the root level of the class.

These should be the same (as far as TS is concerned):

class test1{ /**@type {string}*/ name; }

class test2{ /**@var {string} name */ }