Description
Suggestion
Allow for optional use of typed jsdoc in .ts files when there isn't any TypeScript flavoured syntax for some piece of code.
🔍 Search Terms
is:issue is:open in:title jsdoc in ts
( closest thing i found was #20774 that was closed as "by design" )
✅ Viability Checklist
My suggestion meets these guidelines:
- 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 TypeScript's Design Goals.
⭐ Suggestion
{ "jsdocTypes": true }in tsconfig.json- or automatically detect it and use jsdoc types if there are some...
📃 Motivating Example
Maybe you wish to simply embed some existing js code that you need, it could have a very strict licens that don't allow you to change the code, or you don't want to bother converting the jsdoc into TypeScript flavoured syntax. or maybe you want to slowly move your code over to typescript few bits at the time. Or you maybe just want to try out jsdoc in any case to see what its like. it already allows you to document the code/variables. the feature is there already, it's just disabled... 😞
it could also be that you already have some @typedef code that you just don't want to convert to TypeScript yet (cuz the refactor can be to big or take to long or you perhaps don't want to change it)
if it's disabled by design, can we at least have some config to enable them in tsconfig.json (like allow { "jsdocTypes": true } or something?
in some cases I think that jsdoc can sometimes be more readable than some compact code like this:
const deleteY = <T>(obj: T&{ y?: string; }): Omit<T,'y'> => { ... }
there is just weird symbols everywhere and don't really make that code that much readable and it totally lacks any documentation.
if you are going to document it with a jsdoc block then i think it could as well be optional to type it with jsdoc as well.
// main.ts
/**
* @license some-proprietary Copyright (c) 2017-present, xyz.
* @param {number} a First number.
* @param {number} b Second number.
* @returns {number} The sum of the two numbers.
*/
function add(a, b) {
return a + b;
}this just gives you function add(a: any, b: any): any with some description of the function and arguments & what it returns without any type support at all...
💻 Use Cases
☝️ in motivation...