Promise.coroutine documentation

[liushigit]

I was confused by the doc for the coroutine method, which says the method

Returns a function that can use yield to yield promises.

My understanding of this wording is that, this method "returns a function that may (or may not) yield promises".

But in the provided code example, the returned function is only used as a plain function. There's no "yielded promises" from that function. If this is the example for the "may not" case, shall there be an example for the other case?

What I expected was something like

iter = a.ping()
promise = iter.next().value

[benjamingr]

Yeah that documentation is silly. It takes a function that can use yield to yield promises and returns a promise returning function.

A PR would be welcome

[liushigit]

Here's the coroutine method's source code.

The first sentence may be changed to "Takes a GeneratorFunction producing a generator that yields promise(s), and returns a Promise returning function."

The returned Promise is defined at this line. This promise seems resolved by the value yielded by the generator (see here). If I understand it. (No. see the discussion)

[benjamingr]

@liushigit I'll clarify, I agree that the docs are confusing (and wrong), and if you want to submit a pull request I promise to review it and merge it.

[liushigit]

@benjamingr A PR is added, but I have difficulty explaining the Promise returned by the function returned.

[benjamingr]

@liushigit thanks! I've added some suggestions, LMK what you think

[perrin4869]

I'm not sure if this is the right place to ask this question, but what's the difference performance-wise or other, between using coroutines and async/await in node >= 8? Maybe a note should be added to the documentation about it?

[benjamingr]

@perrin4869 it's likely async/await is still slower than Promise.coroutine at the moment. You can run the bluebird doxbee benchmarks yourself.