Make Outputable instance for HsDocString useful
authorMateusz Kowalczyk <fuuzetsu@fuuzetsu.co.uk>
Tue, 25 Feb 2014 06:35:10 +0000 (06:35 +0000)
committerMateusz Kowalczyk <fuuzetsu@fuuzetsu.co.uk>
Tue, 25 Feb 2014 06:35:49 +0000 (06:35 +0000)
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.

19 files changed:
compiler/hsSyn/HsDoc.hs
testsuite/tests/haddock/haddock_examples/haddock.Test.stderr
testsuite/tests/haddock/should_compile_flag_haddock/haddockA014.stderr
testsuite/tests/haddock/should_compile_flag_haddock/haddockA015.stderr
testsuite/tests/haddock/should_compile_flag_haddock/haddockA016.stderr
testsuite/tests/haddock/should_compile_flag_haddock/haddockA018.stderr
testsuite/tests/haddock/should_compile_flag_haddock/haddockA019.stderr
testsuite/tests/haddock/should_compile_flag_haddock/haddockA020.stderr
testsuite/tests/haddock/should_compile_flag_haddock/haddockA021.stderr
testsuite/tests/haddock/should_compile_flag_haddock/haddockA023.stderr
testsuite/tests/haddock/should_compile_flag_haddock/haddockA024.stderr
testsuite/tests/haddock/should_compile_flag_haddock/haddockA025.stderr
testsuite/tests/haddock/should_compile_flag_haddock/haddockA026.stderr
testsuite/tests/haddock/should_compile_flag_haddock/haddockA027.stderr
testsuite/tests/haddock/should_compile_flag_haddock/haddockA028.stderr
testsuite/tests/haddock/should_compile_flag_haddock/haddockA029.stderr
testsuite/tests/haddock/should_compile_flag_haddock/haddockA030.stderr
testsuite/tests/haddock/should_compile_flag_haddock/haddockA031.stderr
testsuite/tests/haddock/should_compile_flag_haddock/haddockA032.stderr

index 1f3adaf..2cb2854 100644 (file)
@@ -20,7 +20,7 @@ newtype HsDocString = HsDocString FastString
 type LHsDocString = Located HsDocString
 
 instance Outputable HsDocString where
-  ppr _ = text "<document comment>"
+  ppr (HsDocString fs) = ftext fs
 
 ppr_mbDoc :: Maybe LHsDocString -> SDoc
 ppr_mbDoc (Just doc) = ppr doc
index 37a2565..097b6ef 100644 (file)
@@ -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
index f71f89a..a70f624 100644 (file)
@@ -1,6 +1,6 @@
 
 ==================== Parser ====================
-<document comment>
+ a header
 module HeaderTest where
 <document comment>
 x = 0
index 356d5b7..3bfc17d 100644 (file)
@@ -1,6 +1,6 @@
 
 ==================== Parser ====================
-<document comment>
+ a header
 module HeaderTest where
 <document comment>
 x = 0
index 68e7b4f..ca316bc 100644 (file)
@@ -1,7 +1,7 @@
 
 ==================== Parser ====================
 module A (
-       <document comment>, <document comment>
+         bla bla,  blabla 
     ) where
 
 
index 20c6280..2aaa3eb 100644 (file)
@@ -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
 
index edf523d..162c403 100644 (file)
@@ -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
index 2c4f5bc..6d803bb 100644 (file)
@@ -1,10 +1,7 @@
-\r
-==================== Parser ====================\r
-module ShouldCompile where\r
-test ::\r
-  Eq a =>\r
-  [a] <document comment>\r
-  -> [a] <document comment> -> [a] <document comment>\r
-test xs ys = xs\r
-\r
-\r
+
+==================== Parser ====================
+module ShouldCompile where
+test :: Eq a => [a]  doc1  -> [a]  doc2  -> [a]  doc3
+test xs ys = xs
+
+
index f0d269d..b3caa71 100644 (file)
@@ -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
 
 
index 792da55..472ec1a 100644 (file)
@@ -1,7 +1,7 @@
 
 ==================== Parser ====================
 module ShouldCompile where
-test2 :: a <document comment> -> a
+test2 :: a  doc1  -> a
 test2 x = x
 
 
index e352980..3e3cb12 100644 (file)
@@ -1,10 +1,7 @@
-\r
-==================== Parser ====================\r
-module ShouldCompile where\r
-test ::\r
-  Eq a =>\r
-  [a] <document comment>\r
-  -> forall b. [b] <document comment> -> [a] <document comment>\r
-test xs ys = xs\r
-\r
-\r
+
+==================== Parser ====================
+module ShouldCompile where
+test :: Eq a => [a]  doc1  -> forall b. [b]  doc2  -> [a]  doc3
+test xs ys = xs
+
+
index 67bf652..10e88d2 100644 (file)
@@ -1,11 +1,10 @@
-\r
-==================== Parser ====================\r
-module ShouldCompile where\r
-test ::\r
-  [a] <document comment>\r
-  -> forall b. Ord b =>\r
-     [b] <document comment>\r
-     -> forall c. Num c => [c] <document comment> -> [a]\r
-test xs ys zs = xs\r
-\r
-\r
+
+==================== 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
+
+
index 6d9a8b2..fa0d701 100644 (file)
@@ -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
 
 
index aa48d99..820ffa6 100644 (file)
@@ -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
 
 
index c879d22..b0ef139 100644 (file)
@@ -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
 
 
index 75ac294..1d033cd 100644 (file)
@@ -1,9 +1,9 @@
-\r
-==================== Parser ====================\r
-module ShouldCompile where\r
-data A\r
-    = A |\r
-      <document comment> forall a. B a a |\r
-      <document comment> forall a. Num a => C a\r
-\r
-\r
+
+==================== Parser ====================
+module ShouldCompile where
+data A
+  = A |
+     comment for B  forall a. B a a |
+     comment for C  forall a. Num a => C a
+
+
index 2b0e4d2..5cf2d9b 100644 (file)
@@ -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 }