Improve Control.Monad docs
authorNathan Collins <conathan@galois.com>
Sun, 10 Dec 2017 02:59:05 +0000 (18:59 -0800)
committerBen Gamari <ben@smart-cactus.org>
Tue, 2 Jan 2018 21:28:09 +0000 (16:28 -0500)
commit4887c3086149a15a1e16c765682debcfbb9de145
treeff132212cb53435fa470837fb83ba6a6894de4af
parenta67c264201a5d73d3624a73359f36adfaf6ec33c
Improve Control.Monad docs

Summary:
* Reformat Control.Monad.mfilter docs

The formatting was bad, with everything running together, and a
paranthesis was missing. Now the examples and relation between
`filter` and `mfilter` are typeset as code blocks instead of inline.

* Add example to Control.Monad.join docs

The example is using `join . atomically` to run IO actions computed by
STM transactions.

I couldn't figure out how to link to the STM docs in
`Control.Monad.STM`, because that module comes from the `stm` package,
not from `base`, even though `stm` is also part of the GHC source
tree. So, instead I linked to the STM docs in `GHC.Conc`, which seems
inferior to linking to `Control.Monad.STM`, but better than having no
links at all.

* Add example to Control.Monad.forever docs

The example is a simple TCP echo server. To make the uses of `forever`
stand out in the example code, I only link to the non-`forever`
functions (e.g. `forkFinally`) in the import lists.

Reviewers: bgamari, hvr

Subscribers: rwbarton, thomie, carter

Differential Revision: https://phabricator.haskell.org/D4259
libraries/base/Control/Monad.hs