Description
Search Terms
typescript jsdoc inside ts files
Suggestion
It would be great if JSDoc comments in .ts files worked the same as in .js files.
I believe this change is fairly simple to make (because TypeScript already has the implementation to understand JSDoc types).
Use Cases
This brings consistency: JSDoc syntax is already supported in both .ts and .js files, but in .ts files JSDoc comments do not work (do not define types) like they do in .js files.
Examples
This would make it easy for users to choose which form they want to use to define types of things.
It would also give users more flexibility in choosing (or developing) JSDoc tooling without writing WET code.
For example, if a developer wants to document TS code with a non-TS JSDoc tool (for any reason, and there are valid reasons), then they need to define types in both TS and JSDoc, like this:
/** @typedef {{ name: string, age: number }} Bar - A Bar thing of sorts. */ // <-- This is for documentation tooling
export type Bar = { // <-- but we still need to define the type for TS to understand it (WET)
name: string
age: number
}
/** @typedef {Bar & { color: string }} Foo - A Foo type of thing. */ // <-- This is for documentation tooling
export type Foo = Bar & { // <-- but we still need to define the type for TS to understand it (WET)
color: string
}
// This does not need to be documented, it is used only by the library code.
type _PrivateImplementationThing = { hasA: Foo }However, if the user could use JSDoc comments to define types within a .ts file (just like they can in .js files) for things that specifically need to be documented, then they could write the previous example like the following more DRY code:
/** @typedef {{ name: string, age: number }} Bar - A Bar thing of sorts. */ // <-- This is for documentation tooling, and TS understand it.
/** @typedef {Bar & { color: string }} Foo - A Foo type of thing. */ // <-- This is for documentation tooling, and TS understand it.
// This does not (necessarily) need to be documented, it is used only by the library code.
type _PrivateImplementationThing = { hasA: Foo } // same as beforeThe same thing applies to functions, for example. The following is what we currently have to write in order to support non-TSDoc tooling while still declaring types for TypeScript:
/**
* @function foo
* @param {string} a
* @param {number} b
* @return {void}
*/
export function foo(a: string, b: number): void {/*...*/}
// not documented
function bar(a: boolean): boolean {}but with the requested feature in place we could write the following more DRY code:
/**
* @function foo
* @param {string} a
* @param {number} b
* @return {void}
*/
export function foo(a, b) {/*...*/}
// not documented
function bar(a: boolean): boolean {}This would be very supportive of JSDoc tooling that isn't specifically TSDoc. This also gives developers choices (for example, the choice to only document whatever is in JSDoc form, and otherwise ignore the rest, whereas TSDoc tries to document literally everything which is undersirable).
Lastly, having to maintain the WET duplicated type definitions (one for JSDoc tools, one for TypeScript) is error prone, because if the types don't match, TypeScript does not give any error. It would also be great if at least TypeScript warned when comment types don't match source code types, so as to at least prevent errors editing both comments and source.
Checklist
My suggestion meets these guidelines:
- This wouldn't be a breaking change in existing TypeScript/JavaScript code - It may break code that has currently-ignored JSDoc comments within
.tsfiles. - 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, etc.)
- This feature would agree with the rest of TypeScript's Design Goals.