Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for "specialize" tag #59666

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Conversation

apendua
Copy link
Contributor

@apendua apendua commented Aug 17, 2024

Fixes #27387

This is an implementation proposal for @specialize JSDoc tag, which will allow specifying type arguments in JS files. For example if f has a type parameter T, the following JSDoc syntax:

let x = /** @specialize {number} */(f());

will be equivalent to TS:

let x = f<number>();

The tag can be also attached to any other parent node, e.g. assignment statement would also do:

/** @specialize {number} */
let x = f();

Currently, it is also possible to wrap type arguments with <...> as in /** @specialize <number> */,
if that's the preference. I couldn't make up my mind so I allowed both options for now.

The following expressions are also supported:

  • tagged template expression
  • "new" expression
  • JSX element and self-closing tag

I am still planning to add more unit tests, e.g.

  • check if "find all references" works
  • test JSX syntax

Having said that, I've decided to open this PR early (as draft), because there are some open questions where I seek your advice:

  • Is @specialize a good name for this tag? I was also considering @typeArgs, which I think would be a little bit cleaner in communicating its purpose, but I don't like the fact that it consists of two words, as so far there has been no precedence.
  • One issue with @specialize is the fact that some people would prefer to spell it "specialise" and I am worried that it may cause confusion and typing errors in the future.

@typescript-bot typescript-bot added the For Uncommitted Bug PR for untriaged, rejected, closed or missing bug label Aug 17, 2024
@typescript-bot
Copy link
Collaborator

Looks like you're introducing a change to the public API surface area. If this includes breaking changes, please document them on our wiki's API Breaking Changes page.

Also, please make sure @DanielRosenwasser and @RyanCavanaugh are aware of the changes, just as a heads up.

@apendua apendua force-pushed the fix27387 branch 2 times, most recently from 83a1bb2 to 80c2171 Compare August 17, 2024 12:04
@apendua apendua marked this pull request as ready for review August 30, 2024 07:21
@typescript-bot
Copy link
Collaborator

The TypeScript team hasn't accepted the linked issue #27387. If you can get it accepted, this PR will have a better chance of being reviewed.

@Gerrit0
Copy link
Contributor

Gerrit0 commented Sep 22, 2024

Currently, it is also possible to wrap type arguments with <...> as in /** @specialize <number> */,
if that's the preference. I couldn't make up my mind so I allowed both options for now.

Please no. That isn't consistent with how any other type comments are parsed, the extra edge case doesn't just affect TS. @specialize {number} is consistent with @type

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
For Uncommitted Bug PR for untriaged, rejected, closed or missing bug
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Allow to explicitly pass type parameters via JSDoc
3 participants