alt Hacker NewsThis can be done, and is done in some projects, but the problem is that you need to manually maintain both sets of files, which can easily go out of sync if you're not careful. You also lose out on the ability to check your own code - using the header file you've written there, you can't really check the implementation of `useStr` to check that it works.
The advantage of JSDoc is that the TypeScript compiler treats it as equivalent to TypeScript source code, which means you've still got access to type checking inside your functions.
One thing I've seen in a few places is still to have DTS files that declare all sorts of types that are used in the application, and then have those files imported by JSDoc comments. That way, you've got TypeScript syntax for your types, which tend to get bulky and difficult to read in JSDoc syntax, but you still don't need a build system because the DTS imports are ignored completely at runtime.
You can define a declaration file alongside its target however the target does not use the types defined within its declaration within itself - only consumers see the types.
There are three issues with that.
The first is that JSDoc doesn't support everything you need in TypeScript and there is a lot of inlining (like typedef causes collisions, there's no importing a type without also re-exporting it from the importing file unless you inline the import)
The second is that JSDoc isn't picked up from imported libraries (or at least I don't think it is?)
Lastly, you still need a transpiler to remove the comments and build d.ts files.
In the end, JSDoc isn't practical for projects. The header file strategy means you don't need to transpile ever (only a typechecker) and you'd get the full suite of TypeScript functionality - at the cost of synchronization overhead.
For a project using JSDoc, you'll graduate to TypeScript when there is sufficient complexity anyway. Migrating from a d.ts file is way easier (potentially automatable) than migrating from JSDoc.