[commit: ghc] master: Add example to Control.Monad.join docs (a67c264)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/a67c264201a5d73d3624a73359f36adfaf6ec33c/ghc

>---------------------------------------------------------------

commit a67c264201a5d73d3624a73359f36adfaf6ec33c
Author: Nathan Collins <conathan at galois.com>
Date:   Sat Dec 9 18:58:03 2017 -0800

    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.


>---------------------------------------------------------------

a67c264201a5d73d3624a73359f36adfaf6ec33c
 libraries/base/GHC/Base.hs | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/libraries/base/GHC/Base.hs b/libraries/base/GHC/Base.hs
index 35de446..7875fef 100644
--- a/libraries/base/GHC/Base.hs
+++ b/libraries/base/GHC/Base.hs
@@ -596,6 +596,33 @@ liftA3 f a b c = liftA2 f a b <*> c
 -- | The 'join' function is the conventional monad join operator. It
 -- is used to remove one level of monadic structure, projecting its
 -- bound argument into the outer level.
+--
+-- ==== __Examples__
+--
+-- A common use of 'join' is to run an 'IO' computation returned from
+-- an 'GHC.Conc.STM' transaction, since 'GHC.Conc.STM' transactions
+-- can't perform 'IO' directly. Recall that
+--
+-- @
+-- 'GHC.Conc.atomically' :: STM a -> IO a
+-- @
+--
+-- is used to run 'GHC.Conc.STM' transactions atomically. So, by
+-- specializing the types of 'GHC.Conc.atomically' and 'join' to
+--
+-- @
+-- 'GHC.Conc.atomically' :: STM (IO b) -> IO (IO b)
+-- 'join'       :: IO (IO b)  -> IO b
+-- @
+--
+-- we can compose them as
+--
+-- @
+-- 'join' . 'GHC.Conc.atomically' :: STM (IO b) -> IO b
+-- @
+--
+-- to run an 'GHC.Conc.STM' transaction and the 'IO' action it
+-- returns.
 join              :: (Monad m) => m (m a) -> m a
 join x            =  x >>= id