microsoft / microsoft/TypeScript
JSDoc comments for async_hooks are confusing/misleading
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 111k
- Forks
- 14.3k
- Avg merge
- 2d 4h
- Merged PRs (30d)
- 132
Description
Acknowledgement
- I acknowledge that issues using this template may be closed without further explanation at the maintainer's discretion.
Comment
The JSDoc comments from the async_hooks module state not to use the module, and then go on to immediately suggest an "alternative" that is in the module itself.
We strongly discourage the use of the
async_hooksAPI
- AsyncLocalStorage
If you look at the node.js docs, it makes sense because these two things are on separate pages, but in TS, this warning is shown on import { AsyncLocalStorage } from 'node:async_hooks';
This might be a larger codegen/docs issue as well for other modules that have multiple doc pages.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating how JSDoc for the node:async_hooks module is generated and compare its output with the separate Node.js documentation pages. Check whether the warning is attached to the module or to individual exports, including AsyncLocalStorage. Done means the generated TypeScript-facing documentation no longer presents the module warning as applying misleadingly to that export.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- node.js, typescript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100