High level API docs - #105
Conversation
simonmar
left a comment
There was a problem hiding this comment.
Looks good! Just a couple of minor comments
| -- | ||
| -- A slight improvement over the previous example is this: | ||
| -- * Waiting for 2 results ('concurrently'). | ||
| -- * Waiting for /N/ many results ('mapConcurrently' / 'forConcurrently'). |
| -- > page2 <- wait a2 | ||
| -- > ... | ||
| -- Click here to scroll to that section: | ||
| -- "Control.Concurrent.Async#high-level-utilities" (and help implement |
There was a problem hiding this comment.
is this pointer to Haddock relevant here?
There was a problem hiding this comment.
The problem is that haddock renders the link as just Control.Concurrent.Async, which is very confusing beacuse it suggests that it links to the full module, not a section, see screenshot:
I was a bit on the fence whether I should put this call to action to fix it in; I kept it in the first draft so you can see it and decide whether you think it's worth it or whether we should keep async's docs free from petitions to help with tooling :D
There was a problem hiding this comment.
I think "Click here to scroll to that section" is enough of a hint (perhaps "jump" rather than "scroll" though), let's remove the link to the Haddock issue.
96ce3c1 to
db41c89
Compare
This implements Simon Marlow's feedback in PR simonmar#104: > The documentation should start by introducing `withAsync`, > and only later should talk about `async` and `wait`. > It's a bigger restructuring, but I think starting the docs > with some code that you shouldn't use is not the right thing at all To make clear what functions people should usually use, split the introduction into a "High-level" and "Low-level" API, which is terminology I found very successful when it comes to explaining when which function should be used. Also add detail and improve markup in a few places.
This makes it easier for the user to understand which sections they likely need _not_ read.
db41c89 to
1d96dc5
Compare
|
I've updated the PR to implement the feedback. |
|
Thanks! |
| -- * If the operation throws an exception, then that exception is re-thrown | ||
| -- by 'wait'. This ensures property (1): No exception is swallowed. | ||
| -- * If an exception bubbles up through a 'withAsync', then the 'Async' | ||
| -- it spawned its 'cancel'ed. This ensures property (2): No thread is leaked. |
Based on #104.
This implements @simonmar's request from #104 (comment):
There are 2 commits in here on top of #104 (see their commit messages):