Clarify documentation on Caching
- Dominant language
- TypeScript
- Stars
- 777
- Forks
- 1.4k
- Avg merge
- 16h 45m
- Merged PRs (30d)
- 3
Description
The new babel.config.js allows (seemingly requires) you to set up caching. I think the [documentation on caching](https://babeljs.io/docs/en/config-files#apicache) is a little unclear in a couple of spots:
> Any time the using callback returns a value other than the one that was expected...
What is meant by "expected?"
Also, the `.invalidate` explanation seems to have been copied from the `.using` section but not updated. I would like to rewrite it, but I'm a bit confused about how `invalidate` works as well... does it invalidate the cache if it encounters a value different from the immediately previous value? Is it based on a boolean? Will it only invalidate a value that had been used with `.using`? In that case, how do you use them together?
Finally, the suggestion to use a boolean with `.using` raises a question -- this will create a cache for values of `true` and `false`. Thus it seems like once you have used both these values there is no way to invalidate the cache (without adding a `.invalidate` or something). I think this should either be specified if my understanding is correct or clarified if it's incorrect.
I think that the error output if you don't set up caching for `babel` is clearer, at least for `.using`:
> `If this function returns a value different from a previously-encountered value`...
Contributor guide
No contributing guide indexed for this repository
Research direction
Read the linked caching documentation and inspect babel.config.js to understand the .using and .invalidate APIs. Compare their explanations with the quoted error output, then clarify what “expected” means, how invalidation relates to previous values and .using, and whether boolean caching can be invalidated; done when the documentation answers each question accurately.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100