search

microsoft / TypeScript-DOM-lib-generator

Tool for generating dom related TypeScript and JavaScript library files
Apache License 2.0
608 stars 418 forks source link

Add /** @deferred */ comments to deferred callback parameters #1757

Open ahejlsberg opened 1 month ago

ahejlsberg commented 1 month ago

This PR adds /** @deferred */ comments to deferred callback parameters in preparation for https://github.com/microsoft/TypeScript/pull/58729.

github-actions[bot] commented 1 month ago

Thanks for the PR!

This section of the codebase is owned by @saschanaz - if they write a comment saying "LGTM" then it will be merged.

saschanaz commented 1 month ago

You also need to npm run build && npm run baseline-accept.

saschanaz commented 1 month ago

(Looks good. feel free to merge when the TS PR is ready)

saschanaz commented 1 month ago

One question, why not use deferred modifier when we are using TypeScript here? (Edit: Oh, for backward compat, cool.)

saschanaz commented 1 month ago

And another question, is it the requirement here for the callback to be called asynchronously? What happens if those callbacks can be called both sync/async?

ahejlsberg commented 1 month ago

And another question, is it the requirement here for the callback to be called asynchronously?

The deferred modifier (and the /** @deferred */ JSDoc comment) asserts that the callback is never called synchronously. If a synchronous call is a possibility, then the parameter shouldn't have the modifier.

BTW, I haven't been able to find any authoritative documentation on sync vs. async for the various DOM callbacks, so it could well be that some of the modifiers shouldn't be present.