Make Outputable instance for HsDocString useful

Seeing "<document comment>" when trying to debug things in Haddock is
utterly useless and because this instance exists, we can't even make our
own. No instance at all would be better than what it was!

Admittedly, this doesn't produce the nicest output. Perhaps wrapping the
comments in {- -} would be in order but I think it's fine until someone
complains.

18 files changed, 119 insertions, 94 deletions

diff --git a/testsuite/tests/haddock/haddock_examples/haddock.Test.stderr b/testsuite/tests/haddock/haddock_examples/haddock.Test.stderr
index 37a2565a4e..097b6ef1dd 100644
--- a/testsuite/tests/haddock/haddock_examples/haddock.Test.stderr
+++ b/testsuite/tests/haddock/haddock_examples/haddock.Test.stderr
@@ -17,50 +17,74 @@ hidden a = a
 [3 of 3] Compiling Test             ( Test.hs, Test.o )
 
 ==================== Parser ====================
-<document comment>
+
+ Module      :  Test
+ Copyright   :  (c) Simon Marlow 2002
+ License     :  BSD-style
+ 
+ Maintainer  :  libraries@haskell.org
+ Stability   :  provisional
+ Portability :  portable
+
+ This module illustrates & tests most of the features of Haddock.
+ Testing references from the description: 'T', 'f', 'g', 'Visible.visible'.
+
 module Test (
         <IEGroup: 1>, <IEGroup: 2>, T(..), T2, T3(..), T4(..), T5(..),
         T6(..), N1(..), N2(..), N3(..), N4, N5(..), N6(..), N7(..),
-        <IEGroup: 2>, R(..), R1(..), <document comment>, p, q, u,
-        <IEGroup: 1>, C(a, b), D(..), E, F(..), <document comment>, a,
+        <IEGroup: 2>, R(..), R1(..),
+         test that we can export record selectors on their own:, p, q, u,
+        <IEGroup: 1>, C(a, b), D(..), E, F(..),
+         Test that we can export a class method on its own:, a,
         <IEGroup: 1>, f, g, <IEGroup: 1>, <IEDocNamed: aux1>,
         <IEDocNamed: aux2>, <IEDocNamed: aux3>, <IEDocNamed: aux4>,
         <IEDocNamed: aux5>, <IEDocNamed: aux6>, <IEDocNamed: aux7>,
         <IEDocNamed: aux8>, <IEDocNamed: aux9>, <IEDocNamed: aux10>,
-        <IEDocNamed: aux11>, <IEDocNamed: aux12>, <document comment>,
+        <IEDocNamed: aux11>, <IEDocNamed: aux12>,
+         This is some inline documentation in the export list
+
+ > a code block using bird-tracks
+ > each line must begin with > (which isn't significant unless it
+ > is at the beginning of the line).,
         <IEGroup: 1>, module Hidden, <IEGroup: 1>, module Visible,
-        <document comment>, <IEGroup: 1>, Ex(..), <IEGroup: 1>, k, l, m, o,
-        <IEGroup: 1>, <IEGroup: 2>, <document comment>, f'
+         nested-style doc comments , <IEGroup: 1>, Ex(..), <IEGroup: 1>, k,
+        l, m, o, <IEGroup: 1>, <IEGroup: 2>,
+        
+ > a literal line
+
+ $ a non /literal/ line $
+, f'
     ) where
 import Hidden
 import Visible
 <document comment>
 data T a b
-  = <document comment> A Int (Maybe Float) |
-    <document comment> B (T a b, T Int Float)
+  =  This comment describes the 'A' constructor A Int (Maybe Float) |
+     This comment describes the 'B' constructor B (T a b, T Int Float)
 <document comment>
 data T2 a b = T2 a b
 <document comment>
 data T3 a b = A1 a | B1 b
 data T4 a b = A2 a | B2 b
-data T5 a b = <document comment> A3 a | <document comment> B3 b
+data T5 a b =  documents 'A3' A3 a |  documents 'B3' B3 b
 <document comment>
 data T6
-  = <document comment> A4 |
-    <document comment> B4 |
-    <document comment> C4
+  =  This is the doc for 'A4' A4 |
+     This is the doc for 'B4' B4 |
+     This is the doc for 'C4' C4
 <document comment>
 newtype N1 a = N1 a
 <document comment>
 newtype N2 a b = N2 {n :: a b}
 <document comment>
-newtype N3 a b = N3 {n3 :: a b <document comment>}
+newtype N3 a b = N3 {n3 :: a b  this is the 'n3' field }
 <document comment>
 newtype N4 a b = N4 a
-newtype N5 a b = N5 {n5 :: a b <document comment>}
-newtype N6 a b = <document comment> N6 {n6 :: a b}
+newtype N5 a b
+  = N5 {n5 :: a b  no docs on the datatype or the constructor}
+newtype N6 a b =  docs on the constructor only N6 {n6 :: a b}
 <document comment>
-newtype N7 a b = <document comment> N7 {n7 :: a b}
+newtype N7 a b =  The 'N7' constructor N7 {n7 :: a b}
 class D a => C a where
   a :: IO a
   b :: [a]
@@ -83,22 +107,22 @@ class F a where
   ff :: a
 <document comment>
 data R
-  = <document comment>
-    C1 {p :: Int <document comment>,
-        q :: forall a. a -> a <document comment>,
-        r :: Int <document comment>,
-        s :: Int <document comment>} |
-    <document comment>
+  =  This is the 'C1' record constructor, with the following fields:
+    C1 {p :: Int  This comment applies to the 'p' field,
+        q :: forall a. a -> a  This comment applies to the 'q' field,
+        r :: Int  This comment applies to both 'r' and 's',
+        s :: Int  This comment applies to both 'r' and 's'} |
+     This is the 'C2' record constructor, also with some fields:
     C2 {t :: T1
              -> (T2 Int Int) -> (T3 Bool Bool) -> (T4 Float Float) -> T5 () (),
         u :: Int,
         v :: Int}
 <document comment>
 data R1
-  = <document comment>
-    C3 {s1 :: Int <document comment>,
-        s2 :: Int <document comment>,
-        s3 :: Int <document comment>}
+  =  This is the 'C3' record constructor
+    C3 {s1 :: Int  The 's1' record selector,
+        s2 :: Int  The 's2' record selector,
+        s3 :: Int  The 's3' record selector}
 <document comment>
 <document comment>
 <document comment>
@@ -129,19 +153,26 @@ data Ex a
     Ex4 (forall a. a -> a)
 <document comment>
 k ::
-  T () () <document comment>
-  -> (T2 Int Int) <document comment>
-     -> (T3 Bool Bool -> T4 Float Float) <document comment>
-        -> T5 () () <document comment> -> IO () <document comment>
-l :: (Int, Int, Float) <document comment> -> Int <document comment>
-<document comment>
-m :: R -> N1 () <document comment> -> IO Int <document comment>
-<document comment>
-newn :: R <document comment> -> N1 () <document comment> -> IO Int
+  T () ()  This argument has type 'T'
+  -> (T2 Int Int)  This argument has type 'T2 Int Int'
+     -> (T3 Bool Bool
+         -> T4 Float Float)  This argument has type @T3 Bool Bool -> T4 Float Float@
+        -> T5 () ()  This argument has a very long description that should
+ hopefully cause some wrapping to happen when it is finally
+ rendered by Haddock in the generated HTML page.
+           -> IO ()  This is the result type
+l :: (Int, Int, Float)  takes a triple -> Int  returns an 'Int'
+<document comment>
+m ::
+  R -> N1 ()  one of the arguments -> IO Int  and the return value
+<document comment>
+newn ::
+  R  one of the arguments, an 'R'
+  -> N1 ()  one of the arguments -> IO Int
 newn = undefined
 <document comment>
 foreign import ccall unsafe "static header.h o" o
-  :: Float <document comment> -> IO Float <document comment>
+  :: Float  The input float -> IO Float  The output float
 <document comment>
 newp :: Int
 newp = undefined
diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA014.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA014.stderr
index f71f89a89e..a70f624278 100644
--- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA014.stderr
+++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA014.stderr
@@ -1,6 +1,6 @@
 
 ==================== Parser ====================
-<document comment>
+ a header
 module HeaderTest where
 <document comment>
 x = 0
diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA015.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA015.stderr
index 356d5b73bf..3bfc17d811 100644
--- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA015.stderr
+++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA015.stderr
@@ -1,6 +1,6 @@
 
 ==================== Parser ====================
-<document comment>
+ a header
 module HeaderTest where
 <document comment>
 x = 0
diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA016.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA016.stderr
index 1f436a7bec..48dd0870c9 100644
--- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA016.stderr
+++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA016.stderr
@@ -1,6 +1,6 @@
 
 ==================== Parser ====================
-<document comment>
+Module description
 module A where
 
 
diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA018.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA018.stderr
index 1f436a7bec..2aa5245f50 100644
--- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA018.stderr
+++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA018.stderr
@@ -1,6 +1,6 @@
 
 ==================== Parser ====================
-<document comment>
+ module header bla bla 
 module A where
 
 
diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA019.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA019.stderr
index 68e7b4f225..ca316bc8b8 100644
--- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA019.stderr
+++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA019.stderr
@@ -1,7 +1,7 @@
 
 ==================== Parser ====================
 module A (
-	<document comment>, <document comment>
+         bla bla,  blabla 
     ) where
 
 
diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA020.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA020.stderr
index 20c628006d..2aaa3eba98 100644
--- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA020.stderr
+++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA020.stderr
@@ -1,7 +1,7 @@
 
 ==================== Parser ====================
 module A (
-	<document comment>, <document comment>, x, <IEGroup: 2>, <document comment>
+         bla bla,  blabla , x, <IEGroup: 2>,  qweljqwelkqjwelqjkq
     ) where
 x = True
 
diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA021.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA021.stderr
index edf523dfa2..162c403b84 100644
--- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA021.stderr
+++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA021.stderr
@@ -1,8 +1,8 @@
 
 ==================== Parser ====================
 module A (
-	<document comment>, <document comment>, x, <IEGroup: 2>, <document comment>, y,
-	<document comment>, z, <IEGroup: 1>
+         bla bla,  blabla , x, <IEGroup: 2>,  qweljqwelkqjwelqjkq, y,
+         dkashdakj, z, <IEGroup: 1>
     ) where
 x = True
 y = False
diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA023.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA023.stderr
index 2c4f5bc952..6d803bb440 100644
--- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA023.stderr
+++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA023.stderr
@@ -1,10 +1,7 @@
-

-==================== Parser ====================

-module ShouldCompile where

-test ::

-  Eq a =>

-  [a] <document comment>

-  -> [a] <document comment> -> [a] <document comment>

-test xs ys = xs

-

-

+
+==================== Parser ====================
+module ShouldCompile where
+test :: Eq a => [a]  doc1  -> [a]  doc2  -> [a]  doc3
+test xs ys = xs
+
+
diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA024.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA024.stderr
index f0d269d0b1..b3caa71b9e 100644
--- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA024.stderr
+++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA024.stderr
@@ -1,7 +1,7 @@
 
 ==================== Parser ====================
 module ShouldCompile where
-test2 :: a <document comment> -> b <document comment> -> a <document comment>
+test2 :: a  doc1  -> b  doc2  -> a  doc 3 
 test2 x y = x
 
 
diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA025.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA025.stderr
index 792da55155..472ec1a1eb 100644
--- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA025.stderr
+++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA025.stderr
@@ -1,7 +1,7 @@
 
 ==================== Parser ====================
 module ShouldCompile where
-test2 :: a <document comment> -> a
+test2 :: a  doc1  -> a
 test2 x = x
 
 
diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA026.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA026.stderr
index e352980fd4..3e3cb12d10 100644
--- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA026.stderr
+++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA026.stderr
@@ -1,10 +1,7 @@
-

-==================== Parser ====================

-module ShouldCompile where

-test ::

-  Eq a =>

-  [a] <document comment>

-  -> forall b. [b] <document comment> -> [a] <document comment>

-test xs ys = xs

-

-

+
+==================== Parser ====================
+module ShouldCompile where
+test :: Eq a => [a]  doc1  -> forall b. [b]  doc2  -> [a]  doc3
+test xs ys = xs
+
+
diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA027.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA027.stderr
index 67bf6528c0..10e88d2bfc 100644
--- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA027.stderr
+++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA027.stderr
@@ -1,11 +1,10 @@
-

-==================== Parser ====================

-module ShouldCompile where

-test ::

-  [a] <document comment>

-  -> forall b. Ord b =>

-     [b] <document comment>

-     -> forall c. Num c => [c] <document comment> -> [a]

-test xs ys zs = xs

-

-

+
+==================== Parser ====================
+module ShouldCompile where
+test ::
+  [a]  doc1 
+  -> forall b. Ord b =>
+     [b]  doc2  -> forall c. Num c => [c]  doc3 -> [a]
+test xs ys zs = xs
+
+
diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA028.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA028.stderr
index 6d9a8b2181..fa0d7019c0 100644
--- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA028.stderr
+++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA028.stderr
@@ -2,8 +2,7 @@
 ==================== Parser ====================
 module ShouldCompile where
 data (<-->) a b = Mk a b
-test ::
-  [a] <document comment> -> (a <--> (b -> [a])) <document comment>
+test :: [a]  doc1  -> (a <--> (b -> [a]))  blabla
 test xs ys = xs
 
 
diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA029.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA029.stderr
index aa48d998ef..820ffa6708 100644
--- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA029.stderr
+++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA029.stderr
@@ -1,6 +1,7 @@
 
 ==================== Parser ====================
 module ShouldCompile where
-data A = <document comment> A | B | C | D
+data A
+  =  A comment that documents the first constructor A | B | C | D
 
 
diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA030.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA030.stderr
index c879d2244b..b0ef139199 100644
--- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA030.stderr
+++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA030.stderr
@@ -1,6 +1,7 @@
 
 ==================== Parser ====================
 module ShouldCompile where
-data A = <document comment> A | <document comment> B | <document comment> C | D
+data A
+  =  comment for A  A |  comment for B  B |  comment for C   C | D
 
 
diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA031.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA031.stderr
index 75ac2945b8..1d033cd6d7 100644
--- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA031.stderr
+++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA031.stderr
@@ -1,9 +1,9 @@
-

-==================== Parser ====================

-module ShouldCompile where

-data A

-    = A |

-      <document comment> forall a. B a a |

-      <document comment> forall a. Num a => C a

-

-

+
+==================== Parser ====================
+module ShouldCompile where
+data A
+  = A |
+     comment for B  forall a. B a a |
+     comment for C  forall a. Num a => C a
+
+
diff --git a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA032.stderr b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA032.stderr
index 2b0e4d24af..5cf2d9b034 100644
--- a/testsuite/tests/haddock/should_compile_flag_haddock/haddockA032.stderr
+++ b/testsuite/tests/haddock/should_compile_flag_haddock/haddockA032.stderr
@@ -2,9 +2,9 @@
 ==================== Parser ====================
 module ShouldCompile where
 data R a
-    = R {field1 :: a,
-	 field2 :: a <document comment>,
-	 field3 :: a <document comment>,
-	 field4 :: a <document comment>}
+  = R {field1 :: a,
+       field2 :: a  comment for field2,
+       field3 :: a  comment for field3,
+       field4 :: a  comment for field4 }