Some possible documentation clarification

[sirmspencer]

I've been struggling to get promesa implemented correctly, at least with regard to pathom EQL. Just today I think I finally figured out the confusion. fn/macros like p/let and p/-> don’t create a promise, they chain a promise (like .then). So for each async call, you need to create the promise first. The would be with a fn/macro like p/future.

If I am correct, then the documentation can use a little more clarification. p/let and p/future both say they return a promise, but do two completely different things. If there was a clarification of what created a promise verses chained a promise that would go miles.

[sirmspencer]

In retrospect, it might be clear to anyone knowing the difference, but my whole team struggled with this. I think it's possible we came in with some poor examples from a different library, and the language in the promeso docs wasn't enough to overcome that part.

Great work overall!

[niwinz]

concretly, the p/let macro accepts promise and non promise values, and they all will be chained correctly, so technically you don't need to explicit creation of promises. p/let will always return a promise independently of what happened inside the macro context, because it firtly wraps all in promise context.

In any case, you you have concrete doubts or issues with the documentation, please, feel free to ask or contribute an improvement