Feature request: allow using JSDoc types inside .ts files

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 before

The 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 .ts files.
• 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.

[trusktr]

Please don’t close this issue until it has a resolved conversation.

Issue #33189 was closed as a duplicate of #20774 which was closed as a Question with the answer being “the JSDoc type didn’t work in your .ts file because JSDoc works only in .js files and not in .ts files”.

This issue is not a question, but a request for supporting the feature, and I believe it deserves some reasoning instead of being closed as duplicate of an issue that merely mentions why a JSDoc comment didn’t work inside a .ts file.

I believe the example in #20774 is also not intuitive. The type of the parameter is defined, yet intellisense shows the type as any.

This doesn’t help with incremental adoption of TypeScript, because if we convert a very large .js file to .ts, we have to port all the code, instead of just some.

[jamonholmgren]

There’s one feature of JSDoc that isn’t achievable in TypeScript, and that is to type-constrain only one property of an object literal while inferring the rest.

export type FoodType = "burger" | "steak" | "veggies";

const order = {
  customerName: "Bob",
  /** @type {FoodType} */
  food: "steak",
};

In this case, I want the order type to be:

{
  customerName: string; // inferred
  food: FoodType; // specified by JSDoc comment
}

This works in a .js file (assuming you import the FoodType type from a .d.ts file or something), but doesn’t in a .ts file.

I know you can use as FoodType, but that doesn’t constrain FoodType in the literal. It will cast, which I don’t want here.

So this is another vote for allowing JSDoc in TS files, as it would allow me to do this.