Feature request: allow using JSDoc types inside .ts files.

[trusktr]

I am aware of #20774

Search Terms

allow using JSDoc inside TypeScript .ts files.

Suggestion

It would be AWESOME to allow types to be specified in comments inside of .ts files, just like with regular .js files.

Use Cases

I can not (do not want to) work within limitations of, current documentation solutions for TypeScript (f.e. TypeDoc, TSDoc, etc).

I'd rather use a more generic tool that understands JSDoc syntax, without regard for the source code (code agnostic), to make my documentation in a more flexible and customizable way (f.e. JSDOc with commentsOnly plugin which ignores source code, and considers only comments to be the source of truth for documentation.)

However, it'd still be nice not to duplicate types in the comments and in the source, where possible. So if I could write types in the comments (and still optionally have some types in the source as needed, especially for things that don't work in the comments), then that'd be awesome.

Examples

As shown in #20774, it unfortunately does not work.

Also I don't want to switch back to .js and lose certain type features that aren't covered by the commenting features.

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, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

[trusktr]

For now, I'll duplicate all my types, because the flexibility and customizability that I get from handling JSDoc output in my own way is valuable. I don't like the mechanical output from TypeDoc for example, as it covers more than I need and is too complicated.

[trusktr]

@shynome By the way! Continuing from #20774, you can use JSDoc with TypeScript files, using the commentsOnly plugin, which will ignore all the source code, and read only the comments. :)

[sandersn]

Our stance on types from jsdoc hasn't changed since #20774. jsdoc support for Typescript sounds like a better idea to me. In that case you would not use a commentsOnly plugin, but a plugin that understands Typescript.

I'm not sure if the jsdoc maintainers are interested in supporting TS, but it is a large, and growing, chunk of JS code at this point.

For now, I'm marking this as a duplicate of #20774

[typescript-bot]

This issue has been marked as a 'Duplicate' and has seen no recent activity. It has been automatically closed for house-keeping purposes.

[trusktr]

@sandersn If instead of writing

let s: string = 'asdf'

we could also write

/** @type {string} */
let s = 'asdf'

inside of a .ts file (which seems easy because the .js file support is already there), that'd be great. As far as doc generators, it would mean we wouldn't be strictly limited to those that understand TypeScript syntax.

Seems like this is an easy change to make considering the machinery is already implemented. Would the TypeScript team be willing to take a PR that enables this for .ts files?

[typescript-bot]

This issue has been marked as a 'Duplicate' and has seen no recent activity. It has been automatically closed for house-keeping purposes.

[typescript-bot]

This issue has been marked as a 'Duplicate' and has seen no recent activity. It has been automatically closed for house-keeping purposes.

[trusktr]

Can this be re-opened and kept open as a feature request?