Improve Haddock markup

This fixes the markup at the top of `Control.Arrow`, and improves the
markup inside DEPRECATED strings.

(Haddock supports markup inside DEPRECATED messages, which allows to
turn references to Haskell entities into hyperlinks by using the usual
Haddock markup.)

Signed-off-by: Herbert Valerio Riedel <hvr@gnu.org>

9 files changed, 16 insertions, 11 deletions

diff --git a/libraries/base/Control/Arrow.hs b/libraries/base/Control/Arrow.hs
index c971be5d40..b723dd4722 100644
--- a/libraries/base/Control/Arrow.hs
+++ b/libraries/base/Control/Arrow.hs
@@ -10,11 +10,15 @@
 -- Portability :  portable
 --
 -- Basic arrow definitions, based on
+--
 --  * /Generalising Monads to Arrows/, by John Hughes,
 --    /Science of Computer Programming/ 37, pp67-111, May 2000.
+--
 -- plus a couple of definitions ('returnA' and 'loop') from
+--
 --  * /A New Notation for Arrows/, by Ross Paterson, in /ICFP 2001/,
 --    Firenze, Italy, pp229-240.
+--
 -- These papers and more information on arrows can be found at
 -- <http://www.haskell.org/arrows/>.
 
@@ -186,6 +190,7 @@ instance MonadPlus m => ArrowPlus (Kleisli m) where
 
 -- | Choice, for arrows that support it.  This class underlies the
 -- @if@ and @case@ constructs in arrow notation.
+--
 -- Minimal complete definition: 'left', satisfying the laws
 --
 --  * @'left' ('arr' f) = 'arr' ('left' f)@
diff --git a/libraries/base/Control/Concurrent/Chan.hs b/libraries/base/Control/Concurrent/Chan.hs
index 98c2efd013..32387da5bf 100644
--- a/libraries/base/Control/Concurrent/Chan.hs
+++ b/libraries/base/Control/Concurrent/Chan.hs
@@ -136,7 +136,7 @@ unGetChan (Chan readVar _) val = do
    modifyMVar_ readVar $ \read_end -> do
      putMVar new_read_end (ChItem val read_end)
      return new_read_end
-{-# DEPRECATED unGetChan "if you need this operation, use Control.Concurrent.STM.TChan instead.  See http://hackage.haskell.org/trac/ghc/ticket/4154 for details" #-} -- deprecated in 7.0
+{-# DEPRECATED unGetChan "if you need this operation, use Control.Concurrent.STM.TChan instead.  See <http://ghc.haskell.org/trac/ghc/ticket/4154> for details" #-} -- deprecated in 7.0
 
 -- |Returns 'True' if the supplied 'Chan' is empty.
 isEmptyChan :: Chan a -> IO Bool
@@ -145,7 +145,7 @@ isEmptyChan (Chan readVar writeVar) = do
      w <- readMVar writeVar
      let eq = r == w
      eq `seq` return eq
-{-# DEPRECATED isEmptyChan "if you need this operation, use Control.Concurrent.STM.TChan instead.  See http://hackage.haskell.org/trac/ghc/ticket/4154 for details" #-} -- deprecated in 7.0
+{-# DEPRECATED isEmptyChan "if you need this operation, use Control.Concurrent.STM.TChan instead.  See <http://ghc.haskell.org/trac/ghc/ticket/4154> for details" #-} -- deprecated in 7.0
 
 -- Operators for interfacing with functional streams.
 
diff --git a/libraries/base/Control/Concurrent/MVar.hs b/libraries/base/Control/Concurrent/MVar.hs
index c988c626d6..aaf1939855 100644
--- a/libraries/base/Control/Concurrent/MVar.hs
+++ b/libraries/base/Control/Concurrent/MVar.hs
@@ -245,7 +245,7 @@ modifyMVarMasked m io =
     putMVar m a'
     return b
 
-{-# DEPRECATED addMVarFinalizer "use mkWeakMVar instead" #-} -- deprecated in 7.6
+{-# DEPRECATED addMVarFinalizer "use 'mkWeakMVar' instead" #-} -- deprecated in 7.6
 addMVarFinalizer :: MVar a -> IO () -> IO ()
 addMVarFinalizer = GHC.MVar.addMVarFinalizer
 
diff --git a/libraries/base/Data/Bits.hs b/libraries/base/Data/Bits.hs
index f43c8a59ef..16a5b587fe 100644
--- a/libraries/base/Data/Bits.hs
+++ b/libraries/base/Data/Bits.hs
@@ -61,7 +61,7 @@ infixl 7 .&.
 infixl 6 `xor`
 infixl 5 .|.
 
-{-# DEPRECATED bitSize "Use bitSizeMaybe or finiteBitSize instead" #-} -- deprecated in 7.8
+{-# DEPRECATED bitSize "Use 'bitSizeMaybe' or 'finiteBitSize' instead" #-} -- deprecated in 7.8
 
 {-|
 The 'Bits' class defines bitwise operations over integral types.
diff --git a/libraries/base/Data/Typeable/Internal.hs b/libraries/base/Data/Typeable/Internal.hs
index 473b6f43d7..a058dc8f8b 100644
--- a/libraries/base/Data/Typeable/Internal.hs
+++ b/libraries/base/Data/Typeable/Internal.hs
@@ -179,7 +179,7 @@ typeRepArgs :: TypeRep -> [TypeRep]
 typeRepArgs (TypeRep _ _ args) = args
 
 -- | Observe string encoding of a type representation
-{-# DEPRECATED tyConString "renamed to tyConName; tyConModule and tyConPackage are also available." #-} -- deprecated in 7.4
+{-# DEPRECATED tyConString "renamed to 'tyConName'; 'tyConModule' and 'tyConPackage' are also available." #-} -- deprecated in 7.4
 tyConString :: TyCon   -> String
 tyConString = tyConName
 
diff --git a/libraries/base/Debug/Trace.hs b/libraries/base/Debug/Trace.hs
index 67e67b10cd..eedacfa83f 100644
--- a/libraries/base/Debug/Trace.hs
+++ b/libraries/base/Debug/Trace.hs
@@ -79,10 +79,10 @@ traceIO msg = do
 foreign import ccall unsafe "HsBase.h debugBelch2"
    debugBelch :: CString -> CString -> IO ()
 
--- | Deprecated. Use 'traceIO'.
+-- |
 putTraceMsg :: String -> IO ()
 putTraceMsg = traceIO
-{-# DEPRECATED putTraceMsg "Use Debug.Trace.traceIO" #-} -- deprecated in 7.4
+{-# DEPRECATED putTraceMsg "Use 'Debug.Trace.traceIO'" #-} -- deprecated in 7.4
 
 
 {-# NOINLINE trace #-}
diff --git a/libraries/base/Foreign/Marshal/Error.hs b/libraries/base/Foreign/Marshal/Error.hs
index ab90e6d23e..758812b688 100644
--- a/libraries/base/Foreign/Marshal/Error.hs
+++ b/libraries/base/Foreign/Marshal/Error.hs
@@ -79,4 +79,4 @@ throwIfNull  = throwIf (== nullPtr) . const
 --
 void     :: IO a -> IO ()
 void act  = act >> return ()
-{-# DEPRECATED void "use Control.Monad.void instead" #-} -- deprecated in 7.6
+{-# DEPRECATED void "use 'Control.Monad.void' instead" #-} -- deprecated in 7.6
diff --git a/libraries/base/GHC/Exts.hs b/libraries/base/GHC/Exts.hs
index 1cea3fb4a3..a7a04b4be6 100755
--- a/libraries/base/GHC/Exts.hs
+++ b/libraries/base/GHC/Exts.hs
@@ -114,7 +114,7 @@ groupByFB c n eq xs0 = groupByFBCore xs0
 
 traceEvent :: String -> IO ()
 traceEvent = Debug.Trace.traceEventIO
-{-# DEPRECATED traceEvent "Use Debug.Trace.traceEvent or Debug.Trace.traceEventIO" #-} -- deprecated in 7.4
+{-# DEPRECATED traceEvent "Use 'Debug.Trace.traceEvent' or 'Debug.Trace.traceEventIO'" #-} -- deprecated in 7.4
 
 
 {- **********************************************************************
diff --git a/libraries/base/GHC/Generics.hs b/libraries/base/GHC/Generics.hs
index 6480eb1044..1c818588bb 100644
--- a/libraries/base/GHC/Generics.hs
+++ b/libraries/base/GHC/Generics.hs
@@ -622,8 +622,8 @@ data P
 type Rec0  = K1 R
 -- | Type synonym for encoding parameters (other than the last)
 type Par0  = K1 P
-{-# DEPRECATED Par0 "Par0 is no longer used; use Rec0 instead" #-} -- deprecated in 7.6
-{-# DEPRECATED P "P is no longer used; use R instead" #-} -- deprecated in 7.6
+{-# DEPRECATED Par0 "'Par0' is no longer used; use 'Rec0' instead" #-} -- deprecated in 7.6
+{-# DEPRECATED P "'P' is no longer used; use 'R' instead" #-} -- deprecated in 7.6
 
 -- | Tag for M1: datatype
 data D