explain advanced yield usage

[yringler]

I was really scratching my head over that yield business in the useTask generator until I found an article on medium which mentioned it. I put in an explanation in the introduction - even though it's used in other places in the docs, I think it's enough to put it here, because most everyone will start by reading it.

[MartinMalinda]

I wonder how much this explanation is actually needed.

My approach around this so far was:

"You don't need to actually understand generators. Just write yield instead of await. Inside tasks, generator functions behave the same way as async functions. They've been instructed to behave this way by CAF."

https://vue-concurrency.netlify.app/performing-tasks/#performing-tasks

My fear is that explaining generators to people might scare them off. They might think they need to understand generators to use this lib while it is not actually true. You need to understand generators if you wish to interface with them - but in most cases in real world, people just declare them and send them to a 3rd party library - vue-concurrency, redux-saga, bluebird, coroutines, etc.

We could frame this more like a "by the way, if you're curious..."

What do you think?

[yringler]

I personally don't like magic, and was quite spooked by the yield promise. "The value of a yield promise is certainly a promise! What deviltry is this?" But you have a point about not scaring people off. If we suddenly drop a paragraph of intricate JS mechanics on people, it looks like this is a very technically advanced library. What do you think about linking to mozzila instead of CAF? The mozzila case is much smaller and simpler, and it's mozzila, which everyone is familiar with (I must end up on their site a dozen times a day at least). It doesn't deal with async per se, but it gets the idea across that yeild can respectably be used to take a value from the caller, which is the main point.

Maybe something like

If you want to learn more about the yield usage here, check out these docs which explain the underlying syntax. CAF is a real world usage, and is what is used in this project.

[MartinMalinda]

I personally don't like magic, and was quite spooked by the yield promise. "The value of a yield promise is certainly a promise! What deviltry is this?"

I think your case might be a bit unique where you had some insight into generators but not deep enough so you were still confused about this particular usecase. I'd dare to think that most people are either not familiar at all, or familiar well enough. But I could be wrong!

Well placed MDN link with some introduction would definitely be nice though. That I agree with 100%.

What do you think about 👇 ?

Generator functions in vue-concurrency basically behave the same way as async functions, because the underlying code calls .next() on the generator only after promise resolution. Generator functions are flexible though and they can be used for variety of other usecases. See MDN docs for general introduction.