Fix ambiguous/out-of-scope Haddock identifiers

This drastically cuts down on the number of Haddock warnings when making
docs for `base`.  Plus this means more actual links end up in the docs!
Also fixed other small mostly markup issues in the documentation along
the way.

This is a docs-only change.

Reviewers: hvr, bgamari, thomie

Reviewed By: thomie

Subscribers: thomie, rwbarton, carter

Differential Revision: https://phabricator.haskell.org/D5055

8 files changed, 25 insertions, 22 deletions

diff --git a/libraries/base/Control/Arrow.hs b/libraries/base/Control/Arrow.hs
index 377870c88c..8d910277a2 100644
--- a/libraries/base/Control/Arrow.hs
+++ b/libraries/base/Control/Arrow.hs
@@ -76,7 +76,7 @@ infixr 1 ^<<, <<^
 --
 --  * @'first' f >>> 'arr' ('id' *** g) = 'arr' ('id' *** g) >>> 'first' f@
 --
---  * @'first' ('first' f) >>> 'arr' 'assoc' = 'arr' 'assoc' >>> 'first' f@
+--  * @'first' ('first' f) >>> 'arr' assoc = 'arr' assoc >>> 'first' f@
 --
 -- where
 --
@@ -209,7 +209,7 @@ instance MonadPlus m => ArrowPlus (Kleisli m) where
 --
 --  * @'left' f >>> 'arr' ('id' +++ g) = 'arr' ('id' +++ g) >>> 'left' f@
 --
---  * @'left' ('left' f) >>> 'arr' 'assocsum' = 'arr' 'assocsum' >>> 'left' f@
+--  * @'left' ('left' f) >>> 'arr' assocsum = 'arr' assocsum >>> 'left' f@
 --
 -- where
 --
diff --git a/libraries/base/Control/Concurrent/Chan.hs b/libraries/base/Control/Concurrent/Chan.hs
index d0fed4a405..874e48a1a1 100644
--- a/libraries/base/Control/Concurrent/Chan.hs
+++ b/libraries/base/Control/Concurrent/Chan.hs
@@ -102,8 +102,8 @@ writeChan (Chan _ writeVar) val = do
 -- guarantees of 'MVar's (e.g. threads blocked in this operation are woken up in
 -- FIFO order).
 --
--- Throws 'BlockedIndefinitelyOnMVar' when the channel is empty and no other
--- thread holds a reference to the channel.
+-- Throws 'Control.Exception.BlockedIndefinitelyOnMVar' when the channel is
+-- empty and no other thread holds a reference to the channel.
 readChan :: Chan a -> IO a
 readChan (Chan readVar _) = do
   modifyMVar readVar $ \read_end -> do
diff --git a/libraries/base/Control/Concurrent/MVar.hs b/libraries/base/Control/Concurrent/MVar.hs
index fa99361fb1..df28fe8406 100644
--- a/libraries/base/Control/Concurrent/MVar.hs
+++ b/libraries/base/Control/Concurrent/MVar.hs
@@ -33,12 +33,12 @@
 --
 -- === Applicability
 --
--- 'MVar's offer more flexibility than 'IORef's, but less flexibility
--- than 'STM'.  They are appropriate for building synchronization
+-- 'MVar's offer more flexibility than 'Data.IORef.IORef's, but less flexibility
+-- than 'GHC.Conc.STM'.  They are appropriate for building synchronization
 -- primitives and performing simple interthread communication; however
 -- they are very simple and susceptible to race conditions, deadlocks or
 -- uncaught exceptions.  Do not use them if you need perform larger
--- atomic operations such as reading from multiple variables: use 'STM'
+-- atomic operations such as reading from multiple variables: use 'GHC.Conc.STM'
 -- instead.
 --
 -- In particular, the "bigger" functions in this module ('swapMVar',
@@ -70,7 +70,7 @@
 --
 -- 'MVar' operations are always observed to take place in the order
 -- they are written in the program, regardless of the memory model of
--- the underlying machine.  This is in contrast to 'IORef' operations
+-- the underlying machine.  This is in contrast to 'Data.IORef.IORef' operations
 -- which may appear out-of-order to another thread in some cases.
 --
 -- === Example
diff --git a/libraries/base/Control/Exception.hs b/libraries/base/Control/Exception.hs
index 93ba3d5f91..a84005e536 100644
--- a/libraries/base/Control/Exception.hs
+++ b/libraries/base/Control/Exception.hs
@@ -264,7 +264,7 @@ to write something like
 >                 (\e -> handler)
 
 If you need to unmask asynchronous exceptions again in the exception
-handler, 'restore' can be used there too.
+handler, @restore@ can be used there too.
 
 Note that 'try' and friends /do not/ have a similar default, because
 there is no exception handler in this case.  Don't use 'try' for
@@ -332,21 +332,24 @@ kind of situation:
 
 The following operations are guaranteed not to be interruptible:
 
- * operations on 'IORef' from "Data.IORef"
+ * operations on 'Data.IORef.IORef' from "Data.IORef"
 
- * STM transactions that do not use 'retry'
+ * STM transactions that do not use 'GHC.Conc.retry'
 
  * everything from the @Foreign@ modules
 
- * everything from @Control.Exception@ except for 'throwTo'
+ * everything from "Control.Exception" except for 'throwTo'
 
- * @tryTakeMVar@, @tryPutMVar@, @isEmptyMVar@
+ * 'Control.Concurrent.MVar.tryTakeMVar', 'Control.Concurrent.MVar.tryPutMVar',
+   'Control.Concurrent.MVar.isEmptyMVar'
 
- * @takeMVar@ if the @MVar@ is definitely full, and conversely @putMVar@ if the @MVar@ is definitely empty
+ * 'Control.Concurrent.MVar.takeMVar' if the 'Control.Concurrent.MVar.MVar' is
+   definitely full, and conversely 'Control.Concurrent.MVar.putMVar' if the
+   'Control.Concurrent.MVar.MVar' is definitely empty
 
- * @newEmptyMVar@, @newMVar@
+ * 'Control.Concurrent.MVar.newEmptyMVar', 'Control.Concurrent.MVar.newMVar'
 
- * @forkIO@, @forkIOUnmasked@, @myThreadId@
+ * 'Control.Concurrent.forkIO', 'Control.Concurrent.myThreadId'
 
 -}
 
diff --git a/libraries/base/Control/Monad.hs b/libraries/base/Control/Monad.hs
index dd87418995..08c85a8b9b 100644
--- a/libraries/base/Control/Monad.hs
+++ b/libraries/base/Control/Monad.hs
@@ -131,7 +131,7 @@ guard           :: (Alternative f) => Bool -> f ()
 guard True      =  pure ()
 guard False     =  empty
 
--- | This generalizes the list-based 'filter' function.
+-- | This generalizes the list-based 'Data.List.filter' function.
 
 {-# INLINE filterM #-}
 filterM          :: (Applicative m) => (a -> m Bool) -> [a] -> m [a]
@@ -203,7 +203,7 @@ zipWithM_         :: (Applicative m) => (a -> b -> m c) -> [a] -> [b] -> m ()
 {-# INLINE zipWithM_ #-}
 zipWithM_ f xs ys =  sequenceA_ (zipWith f xs ys)
 
-{- | The 'foldM' function is analogous to 'foldl', except that its result is
+{- | The 'foldM' function is analogous to 'Data.Foldable.foldl', except that its result is
 encapsulated in a monad. Note that 'foldM' works from left-to-right over
 the list arguments. This could be an issue where @('>>')@ and the `folded
 function' are not commutative.
diff --git a/libraries/base/Control/Monad/Fail.hs b/libraries/base/Control/Monad/Fail.hs
index 91ef3ed349..ecf974bc79 100644
--- a/libraries/base/Control/Monad/Fail.hs
+++ b/libraries/base/Control/Monad/Fail.hs
@@ -50,13 +50,13 @@ import {-# SOURCE #-} GHC.IO (failIO)
 -- only a single data constructor, and irrefutable patterns (@~pat@).
 --
 -- Instances of 'MonadFail' should satisfy the following law: @fail s@ should
--- be a left zero for '>>=',
+-- be a left zero for 'Control.Monad.>>=',
 --
 -- @
 -- fail s >>= f  =  fail s
 -- @
 --
--- If your 'Monad' is also 'MonadPlus', a popular definition is
+-- If your 'Monad' is also 'Control.Monad.MonadPlus', a popular definition is
 --
 -- @
 -- fail _ = mzero
diff --git a/libraries/base/Control/Monad/Fix.hs b/libraries/base/Control/Monad/Fix.hs
index a58e2828f3..f287b06541 100644
--- a/libraries/base/Control/Monad/Fix.hs
+++ b/libraries/base/Control/Monad/Fix.hs
@@ -40,7 +40,7 @@ import System.IO
 -- Instances of 'MonadFix' should satisfy the following laws:
 --
 -- [/purity/]
---      @'mfix' ('return' . h)  =  'return' ('fix' h)@
+--      @'mfix' ('Control.Monad.return' . h)  =  'Control.Monad.return' ('fix' h)@
 --
 -- [/left shrinking/ (or /tightening/)]
 --      @'mfix' (\\x -> a >>= \\y -> f x y)  =  a >>= \\y -> 'mfix' (\\x -> f x y)@
diff --git a/libraries/base/Control/Monad/ST/Imp.hs b/libraries/base/Control/Monad/ST/Imp.hs
index 4d6b12c119..8ba51e86f0 100644
--- a/libraries/base/Control/Monad/ST/Imp.hs
+++ b/libraries/base/Control/Monad/ST/Imp.hs
@@ -24,7 +24,7 @@ module Control.Monad.ST.Imp (
         runST,
         fixST,
 
-        -- * Converting 'ST' to 'IO'
+        -- * Converting 'ST' to 'Prelude.IO'
         RealWorld,              -- abstract
         stToIO,